abysshub 0.0.1.dev6__tar.gz → 0.0.1.dev8__tar.gz

abysshub-0.0.1.dev8/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: abysshub
+Version: 0.0.1.dev8
+Summary: The official Python library for the Abyss API.
+Project-URL: Homepage, https://abysshub.com
+Project-URL: Source, https://github.com/Abysshub/abysshub-sdk
+Project-URL: Issues, https://github.com/Abysshub/abysshub-sdk/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# abysshub
+
+The official Python library for the [Abyss](https://abysshub.com) API.
+
+Pre-release: the Abyss API opens soon.
+
+```python
+from abysshub import Abyss, AbyssError
+
+abyss = Abyss()  # reads ABYSS_API_KEY
+
+try:
+    run = abyss.run("widget_131", {"amount": 250000})
+    print(run.result)
+except AbyssError as error:
+    print(error.code, error.param, error.request_id, error.run)
+```
+
+`run()` presses the Widget and waits for the run to end, however long it takes, then returns the succeeded run. A refusal or a failed run raises `AbyssError`.
+
+It runs on Python 3.10+, with one dependency, `httpx`.
+
+## The client
+
+```python
+abyss = Abyss(api_key=None, base_url=None, max_retries=2)
+```
+
+- **`api_key`:** defaults to `ABYSS_API_KEY`. Without a key, `Abyss()` raises `AbyssError` with `code == "invalid_api_key"`.
+- **`base_url`:** defaults to `ABYSS_BASE_URL`, else `https://api.abysshub.com`. A key starting `abyss_sk_dev_` goes to `https://api.dev.abysshub.com`.
+
+`abyss.close()` closes its connections; `with Abyss() as abyss:` does it for you.
+
+## Running a Widget
+
+```python
+run = abyss.run(widget, input, max_price=None, idempotency_key=None)
+```
+
+- **`widget`** is `widget_<id>`, or an unlisted Widget's private token.
+- **`input`** is the Widget's Fields by name, as a `dict`.
+- **`max_price`:** the most the run may cost, in Byssium. A higher price is refused with `price_above_max`, and nothing is charged.
+- **`idempotency_key`:** each call presses with a fresh UUID `Idempotency-Key` unless you give one.
+
+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.
+
+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`.
+
+## Errors
+
+A refusal or a failed run raises one `AbyssError`. Branch on `code`:
+
+- **`code`, `message`, `param`, `doc_url`, `request_id`:** from `/v1`'s error body. A failed run's `code` is `widget_fault`, `platform_fault` or `budget_exceeded`.
+- **`status`:** the HTTP status of a refusal; `None` for a failed run.
+- **`run`:** the failed run; `None` for a refusal.
+
+The library's own codes: `invalid_api_key` (no key), `connection_error` (the connection dropped before the API answered) and `unexpected_response` (an answer that is not `/v1`'s).

abysshub-0.0.1.dev8/README.md

@@ -0,0 +1,57 @@
+# abysshub
+
+The official Python library for the [Abyss](https://abysshub.com) API.
+
+Pre-release: the Abyss API opens soon.
+
+```python
+from abysshub import Abyss, AbyssError
+
+abyss = Abyss()  # reads ABYSS_API_KEY
+
+try:
+    run = abyss.run("widget_131", {"amount": 250000})
+    print(run.result)
+except AbyssError as error:
+    print(error.code, error.param, error.request_id, error.run)
+```
+
+`run()` presses the Widget and waits for the run to end, however long it takes, then returns the succeeded run. A refusal or a failed run raises `AbyssError`.
+
+It runs on Python 3.10+, with one dependency, `httpx`.
+
+## The client
+
+```python
+abyss = Abyss(api_key=None, base_url=None, max_retries=2)
+```
+
+- **`api_key`:** defaults to `ABYSS_API_KEY`. Without a key, `Abyss()` raises `AbyssError` with `code == "invalid_api_key"`.
+- **`base_url`:** defaults to `ABYSS_BASE_URL`, else `https://api.abysshub.com`. A key starting `abyss_sk_dev_` goes to `https://api.dev.abysshub.com`.
+
+`abyss.close()` closes its connections; `with Abyss() as abyss:` does it for you.
+
+## Running a Widget
+
+```python
+run = abyss.run(widget, input, max_price=None, idempotency_key=None)
+```
+
+- **`widget`** is `widget_<id>`, or an unlisted Widget's private token.
+- **`input`** is the Widget's Fields by name, as a `dict`.
+- **`max_price`:** the most the run may cost, in Byssium. A higher price is refused with `price_above_max`, and nothing is charged.
+- **`idempotency_key`:** each call presses with a fresh UUID `Idempotency-Key` unless you give one.
+
+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.
+
+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`.
+
+## Errors
+
+A refusal or a failed run raises one `AbyssError`. Branch on `code`:
+
+- **`code`, `message`, `param`, `doc_url`, `request_id`:** from `/v1`'s error body. A failed run's `code` is `widget_fault`, `platform_fault` or `budget_exceeded`.
+- **`status`:** the HTTP status of a refusal; `None` for a failed run.
+- **`run`:** the failed run; `None` for a refusal.
+
+The library's own codes: `invalid_api_key` (no key), `connection_error` (the connection dropped before the API answered) and `unexpected_response` (an answer that is not `/v1`'s).

{abysshub-0.0.1.dev6 → abysshub-0.0.1.dev8}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "abysshub"
-version = "0.0.1.dev6"
+version = "0.0.1.dev8"
 description = "The official Python library for the Abyss API."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.10"
-dependencies = []
+dependencies = ["httpx>=0.27,<1"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Typing :: Typed",

abysshub-0.0.1.dev8/src/abysshub/__init__.py

@@ -0,0 +1,6 @@
+"""The official Python library for the Abyss API."""
+from ._client import Abyss
+from ._error import AbyssError
+from ._run import Run, RunError, RunFile, RunStatus
+
+__all__ = ["Abyss", "AbyssError", "Run", "RunError", "RunFile", "RunStatus"]

abysshub-0.0.1.dev8/src/abysshub/_client.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._error import AbyssError
+from ._http import request, timeouts
+from ._run import Run, RunError, parse_run
+
+API = "https://api.abysshub.com"
+DEV_API = "https://api.dev.abysshub.com"
+DEV_KEY_PREFIX = "abyss_sk_dev_"
+
+REATTACH_PAUSE = 1.0
+"""Seconds between two re-attaches that both ended without the run's ending."""
+
+
+@dataclass
+class _Reply:
+    body: Any
+    run: dict[str, Any] | None
+    cut: bool
+    """Whether the connection was cut, or went silent, after the headers."""
+    location: str | None
+    request_id: str | None
+
+
+class Abyss:
+    """A client for the Abyss API.
+
+    The key defaults to ``ABYSS_API_KEY``, and the address to ``ABYSS_BASE_URL``,
+    else the address the key belongs to.
+    """
+
+    base_url: str
+    max_retries: int
+    """How many times a request is sent again after a drop before any headers, a 429, a 409 or a 5xx."""
+
+    def __init__(self, api_key: str | None = None, base_url: str | None = None, max_retries: int = 2) -> None:
+        if api_key is None:
+            api_key = os.environ.get("ABYSS_API_KEY")
+        if not api_key:
+            raise AbyssError("invalid_api_key", "No Abyss API key: pass api_key, or set ABYSS_API_KEY.")
+        self._api_key = api_key
+        if base_url is None:
+            base_url = os.environ.get("ABYSS_BASE_URL") or (DEV_API if api_key.startswith(DEV_KEY_PREFIX) else API)
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._http = httpx.Client(timeout=timeouts())
+
+    def close(self) -> None:
+        """Closes the client's connections."""
+        self._http.close()
+
+    def __enter__(self) -> Abyss:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def run(
+        self,
+        widget: str,
+        input: Mapping[str, Any],
+        *,
+        max_price: float | None = None,
+        idempotency_key: str | None = None,
+    ) -> Run:
+        """Presses a Widget and waits for the run's ending.
+
+        Re-attaches through ``Location`` whenever the hold ends early. Returns the
+        succeeded run; raises ``AbyssError`` on a refusal or a failed run.
+        """
+        press = self._press(widget, input, max_price, idempotency_key)
+        reply = press if _has_ended(press) else self._hold(self._wait_url(press), _has_ended)
+        assert reply.run is not None
+        run = parse_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)
+        return run
+
+    def _press(
+        self,
+        widget: str,
+        input: Mapping[str, Any],
+        max_price: float | None,
+        idempotency_key: str | None,
+    ) -> _Reply:
+        body: dict[str, Any] = {"input": dict(input)}
+        if max_price is not None:
+            body["max_price"] = max_price
+        headers = {
+            "Content-Type": "application/json",
+            "Idempotency-Key": idempotency_key if idempotency_key is not None else str(uuid.uuid4()),
+        }
+        return self._send("POST", f"{self._widget_url(widget)}/runs", headers, json.dumps(body).encode())
+
+    def _hold(self, url: str, done: Callable[[_Reply], bool]) -> _Reply:
+        """Reads ``url`` until ``done``. Re-attaching has no limit and is not a retry."""
+        reply = self._send("GET", url)
+        while not done(reply):
+            time.sleep(REATTACH_PAUSE)
+            reply = self._send("GET", url)
+        return reply
+
+    def _widget_url(self, widget: str) -> str:
+        return f"{self.base_url}/v1/widgets/{quote(widget, safe='')}"
+
+    def _wait_url(self, reply: _Reply) -> str:
+        location = reply.location or (f"/v1/runs/{quote(reply.run['id'], safe='')}" if reply.run else None)
+        if not location:
+            raise AbyssError(
+                "unexpected_response",
+                "The press answered without a Location to read the run at.",
+                request_id=reply.request_id,
+            )
+        return str(httpx.URL(f"{self.base_url}/").join(location).copy_set_param("wait", "true"))
+
+    def _send(self, method: str, url: str, headers: dict[str, str] | None = None, content: bytes | None = None) -> _Reply:
+        """Sends one request to `/v1`. Every refusal raises at once."""
+        try:
+            answer = request(
+                self._http,
+                method,
+                url,
+                {"Authorization": f"Bearer {self._api_key}", "Accept": "application/json", **(headers or {})},
+                content,
+            )
+        except httpx.TransportError as error:
+            raise AbyssError(
+                "connection_error",
+                "The connection dropped, or timed out, before the API answered.",
+            ) from error
+        request_id = answer.headers.get("request-id")
+        parsed = _parse(answer.text)
+        if answer.status in (200, 202):
+            run = parsed if _is_run(parsed) else None
+            return _Reply(parsed, run, answer.text is None, answer.headers.get("location"), request_id)
+        raise _refusal(answer.status, parsed, request_id)
+
+
+def _refusal(status: int, body: Any, request_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(
+            "unexpected_response",
+            f"The API answered {status} without an error body.",
+            status=status,
+            request_id=request_id,
+        )
+    body_request_id = body.get("request_id")
+    return AbyssError(
+        error["code"],
+        _text(error.get("message")) or error["code"],
+        status=status,
+        param=_text(error.get("param")),
+        doc_url=_text(error.get("doc_url")),
+        request_id=body_request_id if isinstance(body_request_id, str) else request_id,
+    )
+
+
+def _text(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _parse(text: str | None) -> Any:
+    if text is None:
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None
+
+
+def _is_run(value: Any) -> bool:
+    return isinstance(value, dict) and isinstance(value.get("id"), str) and isinstance(value.get("status"), str)
+
+
+def _has_ended(reply: _Reply) -> bool:
+    """Whether the reply carries a run that has succeeded or failed."""
+    return reply.run is not None and reply.run["status"] in ("succeeded", "failed")

abysshub-0.0.1.dev8/src/abysshub/_error.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._run import Run
+
+
+class AbyssError(Exception):
+    """The one error the library raises: a refusal from `/v1`, or a run that failed.
+
+    Branch on ``code``. A failed run carries the run as ``run``.
+    """
+
+    code: str
+    message: str
+    status: int | None
+    """The HTTP status of a refusal; None for a failed run."""
+    param: str | None
+    doc_url: str | None
+    request_id: str | None
+    run: Run | None
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status: int | None = None,
+        param: str | None = None,
+        doc_url: str | None = None,
+        request_id: str | None = None,
+        run: Run | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.param = param
+        self.doc_url = doc_url
+        self.request_id = request_id
+        self.run = run
+
+    def __repr__(self) -> str:
+        return f"AbyssError(code={self.code!r}, message={self.message!r})"

abysshub-0.0.1.dev8/src/abysshub/_http.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+CONNECT_TIMEOUT = 10.0
+"""Seconds to connect."""
+
+SILENCE_TIMEOUT = 30.0
+"""Seconds a response may stay silent before it counts as a cut."""
+
+
+def timeouts(connect: float = CONNECT_TIMEOUT, silence: float = SILENCE_TIMEOUT) -> httpx.Timeout:
+    """httpx's timeouts: ``connect`` to connect, and ``silence`` between any two reads."""
+    return httpx.Timeout(silence, connect=connect)
+
+
+@dataclass
+class Answer:
+    status: int
+    headers: httpx.Headers
+    text: str | None
+    """The whole body, or None when the connection was cut or went silent after the headers."""
+
+
+def request(
+    client: httpx.Client,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    content: bytes | 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.
+    """
+    with client.stream(method, url, headers=headers, content=content) as response:
+        try:
+            body = b"".join(response.iter_bytes())
+        except httpx.TransportError:
+            return Answer(response.status_code, response.headers, None)
+    return Answer(response.status_code, response.headers, body.decode("utf-8", errors="replace"))

abysshub-0.0.1.dev8/src/abysshub/_run.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+RunStatus = Literal["queued", "running", "succeeded", "failed"]
+"""A run's place: ``succeeded`` and ``failed`` are final."""
+
+
+@dataclass
+class RunError:
+    """Why a run failed: ``widget_fault``, ``platform_fault`` or ``budget_exceeded``."""
+
+    code: str
+    message: str
+
+
+@dataclass
+class RunFile:
+    """One file a run wrote. Its ``url`` is signed fresh on every read of the run, and expires."""
+
+    path: str
+    size: int
+    content_type: str
+    url: str
+
+
+@dataclass
+class Run:
+    """A run, with `/v1`'s names."""
+
+    id: str
+    widget: str
+    status: RunStatus
+    price: float
+    result: Any
+    output_files: list[RunFile]
+    error: RunError | None
+    created_at: str
+    started_at: str | None
+    ended_at: str | None
+
+
+def parse_run(data: dict[str, Any]) -> Run:
+    """The run `/v1` sent as ``data``."""
+    error = data.get("error")
+    return Run(
+        id=data["id"],
+        widget=data.get("widget", ""),
+        status=data["status"],
+        price=data.get("price", 0),
+        result=data.get("result"),
+        output_files=[
+            RunFile(path=f["path"], size=f["size"], content_type=f["content_type"], url=f["url"])
+            for f in data.get("output_files") or []
+        ],
+        error=RunError(code=error["code"], message=error["message"]) if isinstance(error, dict) else None,
+        created_at=data.get("created_at", ""),
+        started_at=data.get("started_at"),
+        ended_at=data.get("ended_at"),
+    )

abysshub-0.0.1.dev8/tests/fake_server.py

@@ -0,0 +1,161 @@
+"""The tiny fake server: it replays one recorded exchange file from exchanges/ and
+notes every way the library's requests differ from the recorded ones."""
+from __future__ import annotations
+
+import json
+import re
+import socket
+import threading
+import time
+from collections.abc import Callable
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+EXCHANGES = Path(__file__).resolve().parents[2] / "exchanges"
+UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+CHUNK_PAUSE = 0.005
+
+
+def load_exchanges(pattern: str = "*.json") -> list[dict[str, Any]]:
+    return [{"name": path.name, **json.loads(path.read_text("utf-8"))} for path in sorted(EXCHANGES.glob(pattern))]
+
+
+def fill_every(value: Any, fill: Callable[[str], str]) -> Any:
+    """The value with ``fill`` applied to every string in it, however deep."""
+    if isinstance(value, str):
+        return fill(value)
+    if isinstance(value, list):
+        return [fill_every(item, fill) for item in value]
+    if isinstance(value, dict):
+        return {name: fill_every(item, fill) for name, item in value.items()}
+    return value
+
+
+class Replay:
+    """Serves one recording's exchanges in order, on 127.0.0.1."""
+
+    def __init__(self, recording: dict[str, Any], key: str) -> None:
+        self.recording = recording
+        self.key = key
+        self.problems: list[str] = []
+        self.served = 0
+        self._uuid: str | None = None
+        self._lock = threading.Lock()
+        self._closing = threading.Event()
+        replay = self
+
+        class Handler(BaseHTTPRequestHandler):
+            protocol_version = "HTTP/1.1"
+
+            def log_message(self, format: str, *args: Any) -> None:
+                pass
+
+            def do_GET(self) -> None:
+                replay._serve(self)
+
+            do_POST = do_GET
+
+        self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self._server.daemon_threads = True
+        self.base = f"http://127.0.0.1:{self._server.server_address[1]}"
+        self._thread = threading.Thread(target=self._server.serve_forever, args=(0.01,), daemon=True)
+        self._thread.start()
+
+    def remaining(self) -> int:
+        return len(self.recording["exchanges"]) - self.served
+
+    def close(self) -> None:
+        self._closing.set()
+        self._server.shutdown()
+        self._server.server_close()
+
+    def _fill(self, value: str) -> str:
+        return value.replace("{base}", self.base).replace("{key}", self.key)
+
+    def _differences(self, index: int, req: BaseHTTPRequestHandler, sent: bytes) -> list[str]:
+        exchange = self.recording["exchanges"][index]
+        request = exchange["request"]
+        found = []
+        if req.command != request["method"] or req.path != request["path"]:
+            found.append(f"expected {request['method']} {request['path']}, got {req.command} {req.path}")
+        for name, value in (request.get("headers") or {}).items():
+            got = req.headers.get(name)
+            if value == "{uuid}":
+                ok = bool(UUID.match(got or "")) and (self._uuid is None or got == self._uuid)
+            else:
+                ok = got == self._fill(value)
+            if not ok:
+                found.append(f"header {name} is {got!r}")
+        if exchange.get("storage") and req.headers.get("Authorization") is not None:
+            found.append("storage was sent the API key")
+        if "body" in request and _parse_or_text(sent.decode("utf-8")) != request["body"]:
+            found.append(f"body is {sent.decode('utf-8')}")
+        return found
+
+    def _choose(self, req: BaseHTTPRequestHandler, sent: bytes) -> int | None:
+        with self._lock:
+            index = self.served
+            if index >= len(self.recording["exchanges"]):
+                self.problems.append(f"unexpected {req.command} {req.path}")
+                return None
+            self.served += 1
+            self.problems.extend(f"#{index + 1}: {problem}" for problem in self._differences(index, req, sent))
+            for name, value in (self.recording["exchanges"][index]["request"].get("headers") or {}).items():
+                if value == "{uuid}" and self._uuid is None:
+                    self._uuid = req.headers.get(name)
+            return index
+
+    def _serve(self, req: BaseHTTPRequestHandler) -> None:
+        sent = req.rfile.read(int(req.headers.get("Content-Length") or 0))
+        index = self._choose(req, sent)
+        if index is None:
+            req.send_response(500)
+            req.send_header("Content-Length", "0")
+            req.end_headers()
+            return
+        response = self.recording["exchanges"][index]["response"]
+
+        if response.get("drop"):
+            req.close_connection = True
+            req.connection.shutdown(socket.SHUT_RDWR)
+            return
+        req.send_response(response["status"])
+        if "body" in response:
+            req.send_header("Content-Type", "application/json")
+        for name, value in (response.get("headers") or {}).items():
+            req.send_header(name, self._fill(value))
+        # Chunked, as Node sends it, so a cut is told apart from the body's end.
+        req.send_header("Transfer-Encoding", "chunked")
+        req.end_headers()
+        req.wfile.flush()
+        for chunk in response.get("chunks") or []:
+            time.sleep(CHUNK_PAUSE)
+            _write_chunk(req, chunk.encode())
+        if response.get("cut"):
+            time.sleep(CHUNK_PAUSE)
+            req.close_connection = True
+            req.connection.shutdown(socket.SHUT_RDWR)
+            return
+        if response.get("hold"):
+            self._closing.wait()
+            req.close_connection = True
+            return
+        if "body" in response:
+            _write_chunk(req, json.dumps(fill_every(response["body"], self._fill)).encode())
+        elif response.get("text"):
+            _write_chunk(req, response["text"].encode())
+        req.wfile.write(b"0\r\n\r\n")
+        req.wfile.flush()
+
+
+def _write_chunk(req: BaseHTTPRequestHandler, data: bytes) -> None:
+    req.wfile.write(b"%x\r\n%s\r\n" % (len(data), data))
+    req.wfile.flush()
+
+
+def _parse_or_text(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text

abysshub-0.0.1.dev8/tests/test_client.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import pytest
+
+from abysshub import Abyss, AbyssError
+
+
+@pytest.fixture(autouse=True)
+def no_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("ABYSS_API_KEY", raising=False)
+    monkeypatch.delenv("ABYSS_BASE_URL", raising=False)
+
+
+def test_a_key_goes_to_the_apis_address() -> None:
+    assert Abyss(api_key="abyss_sk_x").base_url == "https://api.abysshub.com"
+
+
+def test_an_abyss_sk_dev_key_goes_to_devs_address() -> None:
+    assert Abyss(api_key="abyss_sk_dev_x").base_url == "https://api.dev.abysshub.com"
+
+
+def test_abyss_base_url_overrides_the_keys_address_and_base_url_overrides_both(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ABYSS_BASE_URL", "http://localhost:8000/")
+    assert Abyss(api_key="abyss_sk_dev_x").base_url == "http://localhost:8000"
+    assert Abyss(api_key="abyss_sk_dev_x", base_url="http://other").base_url == "http://other"
+
+
+def test_the_key_comes_from_abyss_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ABYSS_API_KEY", "abyss_sk_dev_x")
+    assert Abyss().base_url == "https://api.dev.abysshub.com"
+
+
+def test_no_key_raises_abyss_error() -> None:
+    with pytest.raises(AbyssError) as raised:
+        Abyss()
+    assert raised.value.code == "invalid_api_key"
+
+
+def test_max_retries_defaults_to_2() -> None:
+    assert Abyss(api_key="abyss_sk_x").max_retries == 2
+    assert Abyss(api_key="abyss_sk_x", max_retries=0).max_retries == 0

abysshub-0.0.1.dev8/tests/test_http.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import pytest
+from fake_server import Replay
+
+from abysshub._http import request, timeouts
+
+
+def answering(response: dict[str, Any]) -> Replay:
+    return Replay({"exchanges": [{"request": {"method": "GET", "path": "/"}, "response": response}]}, "abyss_sk_x")
+
+
+def get(server: Replay, silence: float = 1.0) -> Any:
+    with httpx.Client(timeout=timeouts(connect=1.0, silence=silence)) as client:
+        return request(client, "GET", f"{server.base}/", {})
+
+
+def test_the_timeouts_are_10_s_to_connect_and_30_s_of_silence() -> None:
+    assert timeouts() == httpx.Timeout(30.0, connect=10.0)
+
+
+def test_silence_after_the_headers_counts_as_a_cut() -> None:
+    server = answering({"status": 200, "chunks": [" "], "hold": True})
+    try:
+        answer = get(server, silence=0.1)
+        assert answer.status == 200
+        assert answer.text is None
+    finally:
+        server.close()
+
+
+def test_a_cut_after_the_headers_answers_no_text() -> None:
+    server = answering({"status": 200, "headers": {"Location": "{base}/v1/runs/run_x"}, "chunks": [" ", " "], "cut": True})
+    try:
+        answer = get(server)
+        assert answer.text is None
+        assert answer.headers["location"] == f"{server.base}/v1/runs/run_x"
+    finally:
+        server.close()
+
+
+def test_a_drop_before_any_headers_raises() -> None:
+    server = answering({"drop": True})
+    try:
+        with pytest.raises(httpx.TransportError):
+            get(server)
+    finally:
+        server.close()
+
+
+def test_a_whole_body_keeps_its_leading_spaces_for_the_caller_to_skip() -> None:
+    server = answering({"status": 200, "chunks": ["  "], "body": {"ok": True}})
+    try:
+        assert get(server).text == '  {"ok": true}'
+    finally:
+        server.close()

abysshub-0.0.1.dev8/tests/test_replay.py

@@ -0,0 +1,81 @@
+"""Every recorded exchange the Python library covers, replayed through the fake server.
+Each must reach the same outcome as in JS."""
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from fake_server import Replay, load_exchanges
+
+from abysshub import Abyss, AbyssError, Run
+
+KEY = "abyss_sk_fake_for_tests"
+RECORDINGS = load_exchanges("run-*.json")
+
+
+def assert_fields(actual: Any, expected: Any, where: str) -> None:
+    """The fields ``expected`` names, however deep: a list must have its length, and an
+    object at least the fields it names."""
+    if isinstance(expected, list):
+        assert isinstance(actual, list), f"{where} is a list"
+        assert len(actual) == len(expected), f"{where} length"
+        for index, item in enumerate(expected):
+            assert_fields(actual[index], item, f"{where}[{index}]")
+    elif isinstance(expected, dict):
+        assert actual is not None, f"{where} is an object"
+        for name, value in expected.items():
+            field = actual[name] if isinstance(actual, dict) else getattr(actual, name)
+            assert_fields(field, value, f"{where}.{name}")
+    else:
+        assert actual == expected, where
+
+
+def perform(abyss: Abyss, call: dict[str, Any]) -> Any:
+    """The recorded call, made through the method it names."""
+    method = call.get("method", "run")
+    options = call.get("options") or {}
+    if method == "run":
+        return abyss.run(call["widget"], call.get("input") or {}, **options)
+    raise AssertionError(f"no such method: {method}")
+
+
+@pytest.mark.parametrize("recording", RECORDINGS, ids=[r["name"] for r in RECORDINGS])
+def test_replay(recording: dict[str, Any]) -> None:
+    server = Replay(recording, KEY)
+    try:
+        client = recording["call"].get("client") or {}
+        with Abyss(api_key=KEY, base_url=server.base, **client) as abyss:
+            try:
+                value, error = perform(abyss, recording["call"]), None
+            except AbyssError as raised:
+                value, error = None, raised
+
+        assert server.problems == []
+        assert server.remaining() == 0, "every recorded request was sent"
+        outcome = recording["outcome"]
+        if "run" in outcome:
+            assert isinstance(value, Run), f"expected a run, got {error!r}"
+            assert_fields(value, outcome["run"], "run")
+        else:
+            assert error is not None, f"expected an AbyssError, got {value!r}"
+            fields = dict(outcome["error"])
+            run = fields.pop("run")
+            assert_fields(error, fields, "error")
+            if run is None:
+                assert error.run is None
+            else:
+                assert_fields(error.run, run, "error.run")
+    finally:
+        server.close()
+
+
+def test_result_is_a_dict() -> None:
+    recording = next(r for r in RECORDINGS if r["name"] == "run-held-success.json")
+    server = Replay(recording, KEY)
+    try:
+        with Abyss(api_key=KEY, base_url=server.base) as abyss:
+            run = abyss.run("widget_131", {"amount": 250000})
+        assert run.result == {"approved": True, "rate": 0.042}
+        assert isinstance(run.result, dict)
+    finally:
+        server.close()

abysshub-0.0.1.dev6/PKG-INFO

@@ -1,21 +0,0 @@
-Metadata-Version: 2.5
-Name: abysshub
-Version: 0.0.1.dev6
-Summary: The official Python library for the Abyss API.
-Project-URL: Homepage, https://abysshub.com
-Project-URL: Source, https://github.com/Abysshub/abysshub-sdk
-Project-URL: Issues, https://github.com/Abysshub/abysshub-sdk/issues
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Programming Language :: Python :: 3
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Provides-Extra: dev
-Requires-Dist: pytest; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# abysshub
-
-The official Python library for the [Abyss](https://abysshub.com) API.
-
-Pre-release: the Abyss API opens soon.

abysshub-0.0.1.dev6/README.md

@@ -1,5 +0,0 @@
-# abysshub
-
-The official Python library for the [Abyss](https://abysshub.com) API.
-
-Pre-release: the Abyss API opens soon.

abysshub-0.0.1.dev6/src/abysshub/__init__.py

@@ -1 +0,0 @@
-"""The official Python library for the Abyss API."""