abysshub 0.1.1.dev5__tar.gz → 0.1.2.dev1__tar.gz

{abysshub-0.1.1.dev5 → abysshub-0.1.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: abysshub
-Version: 0.1.1.dev5
+Version: 0.1.2.dev1
 Summary: The official Python library for the Abyss API.
 Project-URL: Homepage, https://abysshub.com
 Project-URL: Source, https://github.com/Abysshub/abysshub-sdk
@@ -9,7 +9,7 @@ License-Expression: MIT
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.9
 Requires-Dist: httpx<1,>=0.27
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
@@ -35,7 +35,7 @@ except AbyssError as error:
 
 `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`. From async code, use `AsyncAbyss` (see [Async](#async)):
+It runs on Python 3.9+, with one dependency, `httpx`. From async code, use `AsyncAbyss` (see [Async](#async)):
 
 ```python
 async with AsyncAbyss() as abyss:
@@ -71,7 +71,7 @@ run = abyss.run(widget, input, max_price=None, idempotency_key=None, timeout=Non
 
 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`.
+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`, `files` (`ready`, `asleep` or `waking`, see [Old big runs](#old-big-runs)), `error`, `created_at`, `started_at` and `ended_at`.
 
 ## The routes
 
@@ -82,6 +82,7 @@ Under `run()` there is one method per route. Each also takes `timeout=` as a key
 | `abyss.runs.create(widget, input, max_price=None, idempotency_key=None)` | `POST /v1/widgets/{widget}/runs` with `"wait": false` | the `Run`, `queued`, at once |
 | `abyss.runs.get(id, wait=False)` | `GET /v1/runs/{id}`, with `?wait=true` when `wait` | the `Run` |
 | `abyss.runs.list(limit=None, starting_after=None)` | `GET /v1/runs?limit=&starting_after=` | a `RunList`: `data`, `has_more`, newest first |
+| `abyss.runs.wake(id)` | `POST /v1/runs/{id}/wake` | the `Run`, `waking` when it was asleep |
 | `abyss.widgets.get(widget)` | `GET /v1/widgets/{widget}` | a `Widget`: `id`, `name`, `description`, `url`, `price`, `free_runs`, `input_schema` |
 | `abyss.uploads.create(widget, field, filename, size=None)` | `POST /v1/widgets/{widget}/uploads` | an `Upload`: `id`, `upload.url`, `upload.fields` |
 | `abyss.key()` | `GET /v1/key` | a `Key`: `name`, `key`, `user`, `spend_cap`, `spent_this_month`, `created_at` |
@@ -121,9 +122,26 @@ paths = run.save("output")  # [Path("output/charts/a.png"), Path("output/output.
 - **`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}`. A file of 64 MiB or more downloads as 16 parallel byte ranges of its one URL.
 
+## Old big runs
+
+A big run (its files total 50 MiB or more) that nobody has opened for six months falls asleep: its larger files sleep in deep storage, and the run reads `files == "asleep"`. Its `result` reads as before, and reading the run never wakes it. Most callers never meet one.
+
+```python
+from abysshub import FilesAsleepError
+
+try:
+    run.save("output")
+except FilesAsleepError as error:
+    if error.code == "files_asleep":
+        run.wake()  # back within 12 hours, with an email
+```
+
+- **`run.wake()`** (or `abyss.runs.wake(id)`) calls `POST /v1/runs/{id}/wake` and returns the run, `files == "waking"`. Its files are back within 12 hours, when it reads `ready`. Waking a run that is not asleep changes nothing.
+- **`run.save(dir)`** on a run that is `asleep` or `waking` raises `FilesAsleepError`, with `code` `files_asleep` or `files_waking`, before any download.
+
 ## Errors
 
-A refusal, a failed run, a timeout and a lost connection all raise one class, `AbyssError`. There is no class per status: branch on `code`.
+A refusal, a failed run, a timeout and a lost connection all raise one class, `AbyssError`. There is no class per status: branch on `code`. Its one subclass, `FilesAsleepError`, is what `run.save()` raises on an old big run (see [Old big runs](#old-big-runs)).
 
 | Field | |
 |---|---|
@@ -138,9 +156,9 @@ A refusal, a failed run, a timeout and a lost connection all raise one class, `A
 | `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).
+- **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` and `run_files_waking` (409), `rate_limited` (429), `server_error` (500).
 - **A failed run:** `widget_fault`, `platform_fault` or `budget_exceeded`, with the run as `run`.
-- **Library-only codes:** `timeout` (see [Timeouts](#timeouts)); `connection_error`, when the connection still drops before any answer after the retries, with the cause as `__cause__`; and `unexpected_response`, when an answer is not what the route sends.
+- **Library-only codes:** `timeout` (see [Timeouts](#timeouts)); `connection_error`, when the connection still drops before any answer after the retries, with the cause as `__cause__`; `unexpected_response`, when an answer is not what the route sends; and `files_asleep` and `files_waking`, raised by `run.save()` as `FilesAsleepError`.
 
 ## Retries
 
@@ -183,7 +201,7 @@ async with AsyncAbyss() as abyss:  # or abyss = AsyncAbyss(), then await abyss.c
     run = await abyss.runs.get(queued.id, wait=True)
 ```
 
-- **Runs:** it returns an `AsyncRun`, with the same fields as `Run`. Its `save(dir)` and each of its `output_files`' `save(path)` and `read()` are awaited. `runs.list()` returns an `AsyncRunList`, and an `AbyssError` raised by `AsyncAbyss` carries an `AsyncRun` as `run`.
+- **Runs:** it returns an `AsyncRun`, with the same fields as `Run`. Its `save(dir)`, `wake()` and each of its `output_files`' `save(path)` and `read()` are awaited. `runs.list()` returns an `AsyncRunList`, and an `AbyssError` raised by `AsyncAbyss` carries an `AsyncRun` as `run`.
 - **Files** are uploaded as concurrent tasks, each read from disk in a thread.
 - **`timeout=`** stops the waiting, as with `Abyss`. Cancelling the task stops it too, and raises `CancelledError`, not `AbyssError`.
 

{abysshub-0.1.1.dev5 → abysshub-0.1.2.dev1}/README.md

@@ -18,7 +18,7 @@ except AbyssError as error:
 
 `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`. From async code, use `AsyncAbyss` (see [Async](#async)):
+It runs on Python 3.9+, with one dependency, `httpx`. From async code, use `AsyncAbyss` (see [Async](#async)):
 
 ```python
 async with AsyncAbyss() as abyss:
@@ -54,7 +54,7 @@ run = abyss.run(widget, input, max_price=None, idempotency_key=None, timeout=Non
 
 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`.
+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`, `files` (`ready`, `asleep` or `waking`, see [Old big runs](#old-big-runs)), `error`, `created_at`, `started_at` and `ended_at`.
 
 ## The routes
 
@@ -65,6 +65,7 @@ Under `run()` there is one method per route. Each also takes `timeout=` as a key
 | `abyss.runs.create(widget, input, max_price=None, idempotency_key=None)` | `POST /v1/widgets/{widget}/runs` with `"wait": false` | the `Run`, `queued`, at once |
 | `abyss.runs.get(id, wait=False)` | `GET /v1/runs/{id}`, with `?wait=true` when `wait` | the `Run` |
 | `abyss.runs.list(limit=None, starting_after=None)` | `GET /v1/runs?limit=&starting_after=` | a `RunList`: `data`, `has_more`, newest first |
+| `abyss.runs.wake(id)` | `POST /v1/runs/{id}/wake` | the `Run`, `waking` when it was asleep |
 | `abyss.widgets.get(widget)` | `GET /v1/widgets/{widget}` | a `Widget`: `id`, `name`, `description`, `url`, `price`, `free_runs`, `input_schema` |
 | `abyss.uploads.create(widget, field, filename, size=None)` | `POST /v1/widgets/{widget}/uploads` | an `Upload`: `id`, `upload.url`, `upload.fields` |
 | `abyss.key()` | `GET /v1/key` | a `Key`: `name`, `key`, `user`, `spend_cap`, `spent_this_month`, `created_at` |
@@ -104,9 +105,26 @@ paths = run.save("output")  # [Path("output/charts/a.png"), Path("output/output.
 - **`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}`. A file of 64 MiB or more downloads as 16 parallel byte ranges of its one URL.
 
+## Old big runs
+
+A big run (its files total 50 MiB or more) that nobody has opened for six months falls asleep: its larger files sleep in deep storage, and the run reads `files == "asleep"`. Its `result` reads as before, and reading the run never wakes it. Most callers never meet one.
+
+```python
+from abysshub import FilesAsleepError
+
+try:
+    run.save("output")
+except FilesAsleepError as error:
+    if error.code == "files_asleep":
+        run.wake()  # back within 12 hours, with an email
+```
+
+- **`run.wake()`** (or `abyss.runs.wake(id)`) calls `POST /v1/runs/{id}/wake` and returns the run, `files == "waking"`. Its files are back within 12 hours, when it reads `ready`. Waking a run that is not asleep changes nothing.
+- **`run.save(dir)`** on a run that is `asleep` or `waking` raises `FilesAsleepError`, with `code` `files_asleep` or `files_waking`, before any download.
+
 ## Errors
 
-A refusal, a failed run, a timeout and a lost connection all raise one class, `AbyssError`. There is no class per status: branch on `code`.
+A refusal, a failed run, a timeout and a lost connection all raise one class, `AbyssError`. There is no class per status: branch on `code`. Its one subclass, `FilesAsleepError`, is what `run.save()` raises on an old big run (see [Old big runs](#old-big-runs)).
 
 | Field | |
 |---|---|
@@ -121,9 +139,9 @@ A refusal, a failed run, a timeout and a lost connection all raise one class, `A
 | `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).
+- **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` and `run_files_waking` (409), `rate_limited` (429), `server_error` (500).
 - **A failed run:** `widget_fault`, `platform_fault` or `budget_exceeded`, with the run as `run`.
-- **Library-only codes:** `timeout` (see [Timeouts](#timeouts)); `connection_error`, when the connection still drops before any answer after the retries, with the cause as `__cause__`; and `unexpected_response`, when an answer is not what the route sends.
+- **Library-only codes:** `timeout` (see [Timeouts](#timeouts)); `connection_error`, when the connection still drops before any answer after the retries, with the cause as `__cause__`; `unexpected_response`, when an answer is not what the route sends; and `files_asleep` and `files_waking`, raised by `run.save()` as `FilesAsleepError`.
 
 ## Retries
 
@@ -166,7 +184,7 @@ async with AsyncAbyss() as abyss:  # or abyss = AsyncAbyss(), then await abyss.c
     run = await abyss.runs.get(queued.id, wait=True)
 ```
 
-- **Runs:** it returns an `AsyncRun`, with the same fields as `Run`. Its `save(dir)` and each of its `output_files`' `save(path)` and `read()` are awaited. `runs.list()` returns an `AsyncRunList`, and an `AbyssError` raised by `AsyncAbyss` carries an `AsyncRun` as `run`.
+- **Runs:** it returns an `AsyncRun`, with the same fields as `Run`. Its `save(dir)`, `wake()` and each of its `output_files`' `save(path)` and `read()` are awaited. `runs.list()` returns an `AsyncRunList`, and an `AbyssError` raised by `AsyncAbyss` carries an `AsyncRun` as `run`.
 - **Files** are uploaded as concurrent tasks, each read from disk in a thread.
 - **`timeout=`** stops the waiting, as with `Abyss`. Cancelling the task stops it too, and raises `CancelledError`, not `AbyssError`.
 

{abysshub-0.1.1.dev5 → abysshub-0.1.2.dev1}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "abysshub"
-version = "0.1.1.dev5"
+version = "0.1.2.dev1"
 description = "The official Python library for the Abyss API."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.10"
+requires-python = ">=3.9"
 dependencies = ["httpx>=0.27,<1"]
 classifiers = [
     "Programming Language :: Python :: 3",

{abysshub-0.1.1.dev5 → abysshub-0.1.2.dev1}/src/abysshub/__init__.py

@@ -1,9 +1,9 @@
 """The official Python library for the Abyss API."""
 from ._async_client import AsyncAbyss, AsyncRuns, AsyncUploads, AsyncWidgets
 from ._client import Abyss, Runs, Uploads, Widgets
-from ._error import AbyssError
+from ._error import AbyssError, FilesAsleepError
 from ._files import FileData, InputFile, file
-from ._run import AsyncRun, AsyncRunFile, Run, RunError, RunFile, RunStatus
+from ._run import AsyncRun, AsyncRunFile, Run, RunError, RunFile, RunFiles, RunStatus
 from ._types import AsyncRunList, FreeRuns, Key, KeyUser, RunList, Upload, UploadForm, Widget
 
 __all__ = [
@@ -17,6 +17,7 @@ __all__ = [
     "AsyncUploads",
     "AsyncWidgets",
     "FileData",
+    "FilesAsleepError",
     "FreeRuns",
     "InputFile",
     "Key",
@@ -24,6 +25,7 @@ __all__ = [
     "Run",
     "RunError",
     "RunFile",
+    "RunFiles",
     "RunList",
     "RunStatus",
     "Runs",

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

@@ -69,6 +69,12 @@ class AsyncRuns:
         page = await client._get(client._start(timeout), url, _is_run_list, "The run list answered without data.")
         return AsyncRunList(data=[client._run(data) for data in page["data"]], has_more=page["has_more"])
 
+    async def wake(self, id: str, *, timeout: float | None = None) -> AsyncRun:
+        """Wakes a run whose files are asleep, and returns it, ``waking``. A run that is not asleep is returned as it is."""
+        client = self._client
+        reply = await client._send(client._start(timeout), "POST", client._wake_url(id))
+        return client._run(_expect(reply, _is_run, "The wake answered without a run."))
+
 
 class AsyncWidgets:
     """`/v1`'s Widget route, awaited."""
@@ -241,8 +247,11 @@ class AsyncAbyss(_Base[AsyncRun]):
     async def _reread(self, id: str) -> dict[str, Any]:
         return await self._get_run(_Call(None, None), id, False)
 
+    async def _wake(self, id: str, timeout: float | None) -> AsyncRun:
+        return await self.runs.wake(id, timeout=timeout)
+
     def _run(self, data: dict[str, Any]) -> AsyncRun:
-        return parse_async_run(data, self._reread, self._download)
+        return parse_async_run(data, self._reread, self._download, self._wake)
 
     async def _get(self, call: _Call, url: str, is_: Callable[[Any], bool], message: str) -> Any:
         """Reads ``url`` once and returns its body, when it is what the route answers."""

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

@@ -118,6 +118,12 @@ class Runs:
         page = client._get(client._start(timeout), url, _is_run_list, "The run list answered without data.")
         return RunList(data=[client._run(data) for data in page["data"]], has_more=page["has_more"])
 
+    def wake(self, id: str, *, timeout: float | None = None) -> Run:
+        """Wakes a run whose files are asleep, and returns it, ``waking``. A run that is not asleep is returned as it is."""
+        client = self._client
+        reply = client._send(client._start(timeout), "POST", client._wake_url(id))
+        return client._run(_expect(reply, _is_run, "The wake answered without a run."))
+
 
 class Widgets:
     """`/v1`'s Widget route."""
@@ -261,6 +267,9 @@ class _Base(Generic[R]):
     def _run_url(self, id: str, wait: bool) -> str:
         return f"{self.base_url}/v1/runs/{quote(id, safe='')}" + ("?wait=true" if wait else "")
 
+    def _wake_url(self, id: str) -> str:
+        return f"{self._run_url(id, False)}/wake"
+
     def _list_url(self, limit: int | None, starting_after: str | None) -> str:
         params: dict[str, str] = {}
         if limit is not None:
@@ -472,8 +481,11 @@ class Abyss(_Base[Run]):
     def _reread(self, id: str) -> dict[str, Any]:
         return self._get_run(_Call(None, None), id, False)
 
+    def _wake(self, id: str, timeout: float | None) -> Run:
+        return self.runs.wake(id, timeout=timeout)
+
     def _run(self, data: dict[str, Any]) -> Run:
-        return parse_run(data, self._reread, self._download)
+        return parse_run(data, self._reread, self._download, self._wake)
 
     def _get(self, call: _Call, url: str, is_: Callable[[Any], bool], message: str) -> Any:
         """Reads ``url`` once and returns its body, when it is what the route answers."""

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

@@ -57,4 +57,10 @@ class AbyssError(Exception):
         self.run = run
 
     def __repr__(self) -> str:
-        return f"AbyssError(code={self.code!r}, message={self.message!r})"
+        return f"{type(self).__name__}(code={self.code!r}, message={self.message!r})"
+
+
+class FilesAsleepError(AbyssError):
+    """What ``run.save()`` raises when the run's files are asleep, with ``code ==
+    "files_asleep"``: ``run.wake()`` brings them back within 12 hours. While they come back,
+    ``files_waking``. It is an ``AbyssError``, carrying the run as ``run``."""

{abysshub-0.1.1.dev5 → abysshub-0.1.2.dev1}/src/abysshub/_run.py

@@ -7,19 +7,24 @@ from collections.abc import Awaitable, Callable
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Generic, Literal, TypeVar
+from typing import Any, Generic, Literal, Optional, TypeVar
 
-from ._error import AbyssError
+from ._error import AbyssError, FilesAsleepError
 
-Download = Callable[[str, str | None], tuple[int, Callable[[], bytes]]]
+# An alias is evaluated at import, where Python 3.9 has no `X | None`: hence Optional.
+Download = Callable[[str, Optional[str]], tuple[int, Callable[[], bytes]]]
 """Opens a URL in storage, with a ``Range`` header or none: answers its status, and a call
 that reads its content."""
 
 Reread = Callable[[str], dict[str, Any]]
 """Reads a run again with ``GET /v1/runs/{id}``."""
 
-AsyncDownload = Callable[[str, str | None], Awaitable[tuple[int, Callable[[], Awaitable[bytes]]]]]
+Wake = Callable[[str, Optional[float]], "Run"]
+"""Wakes a run with ``POST /v1/runs/{id}/wake``, under a ``timeout`` or none: returns the run."""
+
+AsyncDownload = Callable[[str, Optional[str]], Awaitable[tuple[int, Callable[[], Awaitable[bytes]]]]]
 AsyncReread = Callable[[str], Awaitable[dict[str, Any]]]
+AsyncWake = Callable[[str, Optional[float]], Awaitable["AsyncRun"]]
 
 RANGED_FROM = 64 * 1024 * 1024
 """A file this many bytes or larger downloads as parallel byte ranges: 64 MiB."""
@@ -30,6 +35,11 @@ RANGES = 16
 RunStatus = Literal["queued", "running", "succeeded", "failed"]
 """A run's place: ``succeeded`` and ``failed`` are final."""
 
+RunFiles = Literal["ready", "asleep", "waking"]
+"""Whether a run's files can be read now. A big run nobody has opened for six months falls
+asleep: its larger files sleep until ``run.wake()``, then read ``waking`` until they are
+back, within 12 hours."""
+
 
 @dataclass
 class RunError:
@@ -145,6 +155,7 @@ class _RunFields(Generic[F]):
     created_at: str
     started_at: str | None
     ended_at: str | None
+    files: RunFiles = "ready"
 
     def _targets(self, dir: str | os.PathLike[str]) -> list[tuple[F, Path]]:
         """Each output file with the path it is saved at under ``dir``, refusing one that leaves it."""
@@ -176,9 +187,21 @@ class Run(_RunFields[RunFile]):
     """A run, with `/v1`'s names."""
 
     _reread: Reread | None = field(default=None, init=False, repr=False, compare=False)
+    _wake: Wake | None = field(default=None, init=False, repr=False, compare=False)
+
+    def wake(self, *, timeout: float | None = None) -> Run:
+        """Wakes the run's files with ``POST /v1/runs/{id}/wake`` and returns the run,
+        ``waking`` when it was asleep: its files are back within 12 hours. A run that is not
+        asleep is returned as it is."""
+        if self._wake is None:
+            raise _no_client_to_wake(self.id)
+        return self._wake(self.id, timeout)
 
     def save(self, dir: str | os.PathLike[str]) -> list[Path]:
-        """Saves every output file under ``dir``, at its ``path``, and returns the paths it wrote."""
+        """Saves every output file under ``dir``, at its ``path``, and returns the paths it
+        wrote. A run whose files are asleep or waking raises ``FilesAsleepError`` before any
+        download."""
+        _check_awake(self)
         return [output.save(target) for output, target in self._targets(dir)]
 
     def _refresh_urls(self) -> None:
@@ -192,9 +215,19 @@ class AsyncRun(_RunFields[AsyncRunFile]):
     """``Run`` from ``AsyncAbyss``: ``save()`` is awaited."""
 
     _reread: AsyncReread | None = field(default=None, init=False, repr=False, compare=False)
+    _wake: AsyncWake | None = field(default=None, init=False, repr=False, compare=False)
+
+    async def wake(self, *, timeout: float | None = None) -> AsyncRun:
+        """Wakes the run's files, as ``Run.wake()`` does."""
+        if self._wake is None:
+            raise _no_client_to_wake(self.id)
+        return await self._wake(self.id, timeout)
 
     async def save(self, dir: str | os.PathLike[str]) -> list[Path]:
-        """Saves every output file under ``dir``, at its ``path``, and returns the paths it wrote."""
+        """Saves every output file under ``dir``, at its ``path``, and returns the paths it
+        wrote. A run whose files are asleep or waking raises ``FilesAsleepError`` before any
+        download."""
+        _check_awake(self)
         return [await output.save(target) for output, target in self._targets(dir)]
 
     async def _refresh_urls(self) -> None:
@@ -203,10 +236,17 @@ class AsyncRun(_RunFields[AsyncRunFile]):
             self._refreshed(await self._reread(self.id))
 
 
-def parse_run(data: dict[str, Any], reread: Reread | None = None, download: Download | None = None) -> Run:
-    """The run `/v1` sent as ``data``. With ``reread`` and ``download``, its output files can be read."""
+def parse_run(
+    data: dict[str, Any],
+    reread: Reread | None = None,
+    download: Download | None = None,
+    wake: Wake | None = None,
+) -> Run:
+    """The run `/v1` sent as ``data``. With ``reread`` and ``download``, its output files
+    can be read, and with ``wake`` it can be woken."""
     run = Run(**_fields(data), output_files=[RunFile(**f) for f in _files(data)])
     run._reread = reread
+    run._wake = wake
     for output in run.output_files:
         output._download = download
         output._refresh = run._refresh_urls
@@ -214,11 +254,15 @@ def parse_run(data: dict[str, Any], reread: Reread | None = None, download: Down
 
 
 def parse_async_run(
-    data: dict[str, Any], reread: AsyncReread | None = None, download: AsyncDownload | None = None
+    data: dict[str, Any],
+    reread: AsyncReread | None = None,
+    download: AsyncDownload | None = None,
+    wake: AsyncWake | None = None,
 ) -> AsyncRun:
     """``parse_run()`` for ``AsyncAbyss``."""
     run = AsyncRun(**_fields(data), output_files=[AsyncRunFile(**f) for f in _files(data)])
     run._reread = reread
+    run._wake = wake
     for output in run.output_files:
         output._download = download
         output._refresh = run._refresh_urls
@@ -237,6 +281,7 @@ def _fields(data: dict[str, Any]) -> dict[str, Any]:
         "created_at": data.get("created_at", ""),
         "started_at": data.get("started_at"),
         "ended_at": data.get("ended_at"),
+        "files": data.get("files", "ready"),
     }
 
 
@@ -251,6 +296,21 @@ def _no_client(path: str) -> AbyssError:
     return AbyssError("unexpected_response", f"The output file {path} has no client to download it.")
 
 
+def _check_awake(run: Run | AsyncRun) -> None:
+    """Raises ``FilesAsleepError`` when the run's files are asleep or waking."""
+    if run.files == "asleep":
+        message = f"The files of run {run.id} are asleep. Call run.wake(): they are back within 12 hours."
+    elif run.files == "waking":
+        message = f"The files of run {run.id} are waking after run.wake(): they are back within 12 hours."
+    else:
+        return
+    raise FilesAsleepError(f"files_{run.files}", message, run_id=run.id, run=run)
+
+
+def _no_client_to_wake(id: str) -> AbyssError:
+    return AbyssError("unexpected_response", f"The run {id} has no client to wake it.", run_id=id)
+
+
 def _downloaded(path: str, status: int, content: bytes) -> bytes:
     if not 200 <= status < 300:
         raise _answered(path, status)

{abysshub-0.1.1.dev5 → abysshub-0.1.2.dev1}/tests/caller.py

@@ -46,6 +46,8 @@ def perform(abyss: Abyss, call: dict[str, Any], input: dict[str, Any]) -> Any:
         return abyss.runs.get(call["id"], **options)
     if method == "runs.list":
         return abyss.runs.list(**options)
+    if method == "runs.wake":
+        return abyss.runs.wake(call["id"], **options)
     if method == "widgets.get":
         return abyss.widgets.get(call["widget"], **options)
     if method == "uploads.create":
@@ -67,6 +69,8 @@ async def perform_async(abyss: AsyncAbyss, call: dict[str, Any], input: dict[str
         return await abyss.runs.get(call["id"], **options)
     if method == "runs.list":
         return await abyss.runs.list(**options)
+    if method == "runs.wake":
+        return await abyss.runs.wake(call["id"], **options)
     if method == "widgets.get":
         return await abyss.widgets.get(call["widget"], **options)
     if method == "uploads.create":

{abysshub-0.1.1.dev5 → abysshub-0.1.2.dev1}/tests/test_replay.py

@@ -10,9 +10,11 @@ import pytest
 from caller import caller_input, perform, perform_async, with_files
 from fake_server import Replay, load_exchanges, pattern
 
-from abysshub import Abyss, AbyssError, AsyncAbyss, AsyncRun, Run
+from abysshub import Abyss, AbyssError, AsyncAbyss, AsyncRun, FilesAsleepError, Run
 
 KEY = "abyss_sk_fake_for_tests"
+FILES_ASLEEP = {"files_asleep", "files_waking"}
+"""The codes ``run.save()`` raises as ``FilesAsleepError``."""
 RECORDINGS = load_exchanges()
 
 
@@ -33,19 +35,26 @@ def assert_fields(actual: Any, expected: Any, where: str) -> None:
         assert actual == expected, where
 
 
-def call_sync(base: str, call: dict[str, Any], dir: Path, files: dict[str, str]) -> tuple[Any, Any, Any]:
-    """The recorded call through ``Abyss``: its value, its error and what ``run.save()`` answered."""
+def call_sync(base: str, call: dict[str, Any], dir: Path, files: dict[str, str]) -> tuple[Any, Any, Any, Any]:
+    """The recorded call through ``Abyss``: its value, its error, what ``run.save()``
+    answered or raised, and what ``run.wake()`` answered."""
     save = call.get("save")
     with Abyss(api_key=KEY, base_url=base, **(call.get("client") or {})) as abyss:
         try:
             value, error = perform(abyss, call, caller_input(call.get("input") or {}, dir, files)), None
         except AbyssError as raised:
             value, error = None, raised
-        saved = value.save(dir / save) if save and isinstance(value, Run) else None
-    return value, error, saved
+        saved: Any = None
+        if save and isinstance(value, Run):
+            try:
+                saved = value.save(dir / save)
+            except AbyssError as raised:
+                saved = raised
+        woken = value.wake() if call.get("wake") and isinstance(value, Run) else None
+    return value, error, saved, woken
 
 
-async def call_async(base: str, call: dict[str, Any], dir: Path, files: dict[str, str]) -> tuple[Any, Any, Any]:
+async def call_async(base: str, call: dict[str, Any], dir: Path, files: dict[str, str]) -> tuple[Any, Any, Any, Any]:
     """The recorded call through ``AsyncAbyss``."""
     save = call.get("save")
     async with AsyncAbyss(api_key=KEY, base_url=base, **(call.get("client") or {})) as abyss:
@@ -53,8 +62,14 @@ async def call_async(base: str, call: dict[str, Any], dir: Path, files: dict[str
             value, error = await perform_async(abyss, call, caller_input(call.get("input") or {}, dir, files)), None
         except AbyssError as raised:
             value, error = None, raised
-        saved = await value.save(dir / save) if save and isinstance(value, AsyncRun) else None
-    return value, error, saved
+        saved: Any = None
+        if save and isinstance(value, AsyncRun):
+            try:
+                saved = await value.save(dir / save)
+            except AbyssError as raised:
+                saved = raised
+        woken = await value.wake() if call.get("wake") and isinstance(value, AsyncRun) else None
+    return value, error, saved, woken
 
 
 @pytest.mark.parametrize("client", ["Abyss", "AsyncAbyss"])
@@ -67,13 +82,15 @@ def test_replay(recording: dict[str, Any], client: str) -> None:
     try:
         with with_files(files) as dir:
             if client == "Abyss":
-                value, error, saved = call_sync(server.base, call, dir, files)
+                value, error, saved, woken = call_sync(server.base, call, dir, files)
             else:
-                value, error, saved = asyncio.run(call_async(server.base, call, dir, files))
+                value, error, saved, woken = asyncio.run(call_async(server.base, call, dir, files))
+            outcome = recording["outcome"]
+            if isinstance(saved, AbyssError) and "save_error" not in outcome:
+                raise saved
 
             assert server.problems == []
             assert server.remaining() == 0, "every recorded request was sent"
-            outcome = recording["outcome"]
             if "run" in outcome:
                 assert isinstance(value, (Run, AsyncRun)), f"expected a run, got {error!r}"
                 assert_fields(value, outcome["run"], "run")
@@ -89,6 +106,13 @@ def test_replay(recording: dict[str, Any], client: str) -> None:
                     assert error.run is None
                 else:
                     assert_fields(error.run, run, "error.run")
+            if "save_error" in outcome:
+                assert isinstance(saved, AbyssError), f"expected run.save() to raise, got {saved!r}"
+                assert isinstance(saved, FilesAsleepError) == (outcome["save_error"]["code"] in FILES_ASLEEP)
+                assert_fields(saved, outcome["save_error"], "save_error")
+            if "woken" in outcome:
+                assert isinstance(woken, (Run, AsyncRun)), f"expected run.wake() to return a run, got {woken!r}"
+                assert_fields(woken, outcome["woken"], "woken")
             if "saved" in outcome:
                 assert saved == [dir / save / path for path in outcome["saved"]], "run.save() returns the paths it wrote"
                 # A saved ``pattern`` is a whole file of that many generated bytes.