abysshub 0.0.1.dev7__tar.gz → 0.0.1.dev9__tar.gz

abysshub-0.0.1.dev9/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: abysshub
+Version: 0.0.1.dev9
+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`.
+
+## Files
+
+```python
+from abysshub import Abyss, file
+
+run = abyss.run("widget_1660", {
+    "report": file("report.pdf"),
+    "data": [file("jan.csv"), file(csv_bytes, filename="feb.csv"), "https://example.com/sales/mar.csv"],
+})
+paths = run.save("output")  # [Path("output/charts/a.png"), Path("output/output.json")]
+```
+
+- **`file(path)`** is a file on disk, read when it is uploaded. A file Field also takes a `Path`, an open file (`open("report.pdf", "rb")`) or `bytes`. `file(data, filename=...)` names data. A file without a name uploads under its Field's name.
+- **A string passes through** as an `https` URL or an upload id. A multi-file Field takes a list, which may mix all three kinds.
+- **Before the press,** each file is uploaded with `POST /v1/widgets/{widget}/uploads`, then sent to storage, in parallel, and its id goes in the input. An upload refusal (`held_input_*`) raises before any press. A press that drops before any headers is sent again with the same ids; it never uploads again.
+- **`run.save(dir)`** writes every output file under `dir` at its `path`, making folders, and returns the paths it wrote.
+- **Each of `run.output_files`** has `f.save(path)` and `f.read()`, which returns `bytes`. An expired URL is refreshed once, by reading the run again with `GET /v1/runs/{id}`.
+
+## 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.dev9/README.md

@@ -0,0 +1,75 @@
+# 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`.
+
+## Files
+
+```python
+from abysshub import Abyss, file
+
+run = abyss.run("widget_1660", {
+    "report": file("report.pdf"),
+    "data": [file("jan.csv"), file(csv_bytes, filename="feb.csv"), "https://example.com/sales/mar.csv"],
+})
+paths = run.save("output")  # [Path("output/charts/a.png"), Path("output/output.json")]
+```
+
+- **`file(path)`** is a file on disk, read when it is uploaded. A file Field also takes a `Path`, an open file (`open("report.pdf", "rb")`) or `bytes`. `file(data, filename=...)` names data. A file without a name uploads under its Field's name.
+- **A string passes through** as an `https` URL or an upload id. A multi-file Field takes a list, which may mix all three kinds.
+- **Before the press,** each file is uploaded with `POST /v1/widgets/{widget}/uploads`, then sent to storage, in parallel, and its id goes in the input. An upload refusal (`held_input_*`) raises before any press. A press that drops before any headers is sent again with the same ids; it never uploads again.
+- **`run.save(dir)`** writes every output file under `dir` at its `path`, making folders, and returns the paths it wrote.
+- **Each of `run.output_files`** has `f.save(path)` and `f.read()`, which returns `bytes`. An expired URL is refreshed once, by reading the run again with `GET /v1/runs/{id}`.
+
+## 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.dev7 → abysshub-0.0.1.dev9}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "abysshub"
-version = "0.0.1.dev7"
+version = "0.0.1.dev9"
 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.dev9/src/abysshub/__init__.py

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

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

@@ -0,0 +1,269 @@
+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 ._files import upload_files
+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."""
+
+RETRY_PAUSE = 0.5
+"""Seconds before the first retry after a drop; the pause doubles with each retry."""
+
+
+@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:
+        """Uploads the input's files, presses a Widget and waits for the run's ending.
+
+        A file Field takes ``file(path)``, a ``Path``, an open file or ``bytes``, or a
+        list of them; a string passes through as an ``https`` URL or an upload id.
+        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 = 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)
+        return run
+
+    def _press(
+        self,
+        widget: str,
+        input: Mapping[str, Any],
+        max_price: float | None,
+        idempotency_key: str | None,
+    ) -> _Reply:
+        """Uploads the input's files and sends the press. Its retries send the same body
+        and ``Idempotency-Key``, so the uploads are never redone."""
+        widget_url = self._widget_url(widget)
+        uploaded = upload_files(input, lambda field, filename, data: self._upload(widget_url, field, filename, data))
+        body: dict[str, Any] = {"input": uploaded}
+        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"{widget_url}/runs", headers, json.dumps(body).encode())
+
+    def _upload(self, widget_url: str, field: str, filename: str, data: bytes) -> str:
+        """Asks for an upload, sends the file to storage and answers the upload's id."""
+        grant = self._send(
+            "POST",
+            f"{widget_url}/uploads",
+            {"Content-Type": "application/json"},
+            json.dumps({"field": field, "filename": filename, "size": len(data)}).encode(),
+        )
+        if not _is_upload(grant.body):
+            raise AbyssError(
+                "unexpected_response",
+                "The upload answered without an id and a form.",
+                request_id=grant.request_id,
+            )
+        upload = grant.body["upload"]
+        try:
+            stored = self._http.post(
+                upload["url"],
+                data={name: str(value) for name, value in upload["fields"].items()},
+                files={"file": (filename, data)},
+            )
+        except httpx.TransportError as error:
+            raise AbyssError(
+                "connection_error",
+                f"The connection to storage dropped during the upload of {filename}.",
+                param=field,
+            ) from error
+        if not stored.is_success:
+            raise AbyssError(
+                "unexpected_response",
+                f"Storage answered {stored.status_code} to the upload of {filename}.",
+                status=stored.status_code,
+                param=field,
+            )
+        return str(grant.body["id"])
+
+    def _download(self, url: str) -> tuple[int, bytes]:
+        """Downloads an output file from storage, without the API key."""
+        try:
+            response = self._http.get(url)
+        except httpx.TransportError as error:
+            raise AbyssError("connection_error", "The connection to storage dropped during a download.") from error
+        return response.status_code, response.content
+
+    def _reread(self, id: str) -> dict[str, Any]:
+        """Reads a run with ``GET /v1/runs/{id}``. A cut read is read again."""
+        reply = self._hold(f"{self.base_url}/v1/runs/{quote(id, safe='')}", lambda reply: not reply.cut)
+        if reply.run is None:
+            raise AbyssError("unexpected_response", "The read answered without a run.", request_id=reply.request_id)
+        return reply.run
+
+    def _run(self, data: dict[str, Any]) -> Run:
+        return parse_run(data, self._reread, self._download)
+
+    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`. A drop before any headers is sent again, at most
+        ``max_retries`` times; every refusal raises at once."""
+        sent_headers = {"Authorization": f"Bearer {self._api_key}", "Accept": "application/json", **(headers or {})}
+        attempt = 0
+        while True:
+            try:
+                answer = request(self._http, method, url, sent_headers, content)
+                break
+            except httpx.TransportError as error:
+                if attempt >= self.max_retries:
+                    raise AbyssError(
+                        "connection_error",
+                        "The connection dropped, or timed out, before the API answered.",
+                    ) from error
+                time.sleep(RETRY_PAUSE * 2**attempt)
+                attempt += 1
+        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 _is_upload(value: Any) -> bool:
+    if not isinstance(value, dict) or not isinstance(value.get("id"), str):
+        return False
+    upload = value.get("upload")
+    return isinstance(upload, dict) and isinstance(upload.get("url"), str) and isinstance(upload.get("fields"), dict)
+
+
+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.dev9/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.dev9/src/abysshub/_files.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Mapping
+from concurrent.futures import Future, ThreadPoolExecutor
+from pathlib import Path
+from typing import IO, Any, Union
+
+FileData = Union[bytes, bytearray, memoryview, os.PathLike[str], IO[bytes], IO[str]]
+"""File data: bytes in memory, a ``Path``, or an open file."""
+
+MAX_PARALLEL_UPLOADS = 8
+
+
+class InputFile:
+    """A file for a file Field: a path, read when it is uploaded, or data. Made by ``file()``."""
+
+    source: str | FileData
+    filename: str | None
+    """The name to upload under. Defaults to the path's or the open file's name, else the Field's name."""
+
+    def __init__(self, source: str | FileData, filename: str | None = None) -> None:
+        self.source = source
+        self.filename = filename
+
+    def __repr__(self) -> str:
+        return f"file({self.source!r})"
+
+
+def file(source: str | FileData, *, filename: str | None = None) -> InputFile:
+    """A file for a file Field. A string is a path, read when the file is uploaded."""
+    return InputFile(source, filename)
+
+
+Uploader = Callable[[str, str, bytes], str]
+"""Uploads one file for a Field, by its name and content, and answers the upload's id."""
+
+
+def upload_files(input: Mapping[str, Any], upload: Uploader) -> dict[str, Any]:
+    """The input with every file value uploaded, in parallel, and replaced by its upload's id.
+
+    Strings pass through as an ``https`` URL or an upload id, and a list may mix all
+    kinds. The caller's input is never changed.
+    """
+    uploaded = dict(input)
+    jobs: list[tuple[Callable[[str], None], str, InputFile | FileData]] = []
+    for field, value in input.items():
+        if is_file(value):
+            jobs.append((_setter(uploaded, field), field, value))
+        elif isinstance(value, list) and any(is_file(item) for item in value):
+            items = list(value)
+            uploaded[field] = items
+            jobs.extend((_setter(items, index), field, item) for index, item in enumerate(value) if is_file(item))
+    if not jobs:
+        return uploaded
+
+    def upload_one(field: str, value: InputFile | FileData) -> str:
+        filename, data = _load(value, field)
+        return upload(field, filename, data)
+
+    with ThreadPoolExecutor(max_workers=min(len(jobs), MAX_PARALLEL_UPLOADS)) as pool:
+        futures: list[Future[str]] = [pool.submit(upload_one, field, value) for _, field, value in jobs]
+    for (put, _, _), future in zip(jobs, futures):
+        put(future.result())
+    return uploaded
+
+
+def is_file(value: Any) -> bool:
+    """Whether the value is a file to upload, rather than a Field's plain value."""
+    return isinstance(value, (InputFile, bytes, bytearray, memoryview, os.PathLike)) or callable(
+        getattr(value, "read", None)
+    )
+
+
+def _setter(target: Any, at: Any) -> Callable[[str], None]:
+    def put(upload_id: str) -> None:
+        target[at] = upload_id
+
+    return put
+
+
+def _load(value: InputFile | FileData, field: str) -> tuple[str, bytes]:
+    """The file's name and content."""
+    given = value if isinstance(value, InputFile) else InputFile(value)
+    source = given.source
+    if isinstance(source, (str, os.PathLike)):
+        path = Path(source)
+        return given.filename or path.name, path.read_bytes()
+    if isinstance(source, (bytes, bytearray, memoryview)):
+        return given.filename or field, bytes(source)
+    content = source.read()
+    data = content.encode("utf-8") if isinstance(content, str) else bytes(content)
+    name = getattr(source, "name", None)
+    return given.filename or (Path(name).name if isinstance(name, str) and name else field), data

abysshub-0.0.1.dev9/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"))