b3os 0.0.1__py3-none-any.whl

b3os/__init__.py

@@ -0,0 +1,64 @@
+"""b3os: the Python SDK for B3OS beta.
+
+    from b3os import B3OS
+    b3 = B3OS()                       # B3OS_API_KEY, or the node socket / sandbox URL
+    page = b3.vision.scrape({"url": "https://example.com"})
+    sbx = b3.sandboxes.create_sandbox({"template": "base"})
+    out = b3.sandboxes.exec(sbx["id"], {"cmd": "python3 -c 'print(2 + 2)'"})
+
+Async: `from b3os import AsyncB3OS`, same namespaces with `await`.
+"""
+
+from ._async import AsyncEventStream, AsyncJobEventStream, AsyncPage
+from ._base import DEFAULT_BASE_URL, DEFAULT_SOCKET_PATH
+from ._errors import CLIENT_ERROR_CODES, B3OSConnectionError, B3OSError, B3OSJobError, B3OSTimeoutError
+from ._generated import types
+from ._generated.clients import AsyncB3OS, B3OS
+from ._generated.errors import ERROR_CATALOG
+from ._options import CdpEndpoint, RequestOptions, TicketedUrl
+from ._pty import AsyncPtySession, PtyExit, PtySession
+from ._response import ResponseInfo, response_of
+from ._sse import SSEDecoder, SSEMessage
+from ._sync import EventStream, JobEventStream, Page
+from ._timing import ServerTiming, ServerTimingEntry, parse_server_timing
+from ._util import SDK_VERSION
+from ._webhooks import WebhookVerificationError, sign_webhook, verify_webhook
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "B3OS",
+    "AsyncB3OS",
+    "B3OSError",
+    "B3OSConnectionError",
+    "B3OSTimeoutError",
+    "B3OSJobError",
+    "CLIENT_ERROR_CODES",
+    "ERROR_CATALOG",
+    "EventStream",
+    "JobEventStream",
+    "AsyncEventStream",
+    "AsyncJobEventStream",
+    "Page",
+    "AsyncPage",
+    "RequestOptions",
+    "ResponseInfo",
+    "response_of",
+    "ServerTiming",
+    "ServerTimingEntry",
+    "parse_server_timing",
+    "SSEDecoder",
+    "SSEMessage",
+    "TicketedUrl",
+    "CdpEndpoint",
+    "PtySession",
+    "AsyncPtySession",
+    "PtyExit",
+    "verify_webhook",
+    "sign_webhook",
+    "WebhookVerificationError",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_SOCKET_PATH",
+    "SDK_VERSION",
+    "types",
+]

b3os/_async.py

@@ -0,0 +1,563 @@
+"""The asynchronous client core (httpx.AsyncClient; asyncio or trio through anyio). Same behavior as _sync.py."""
+
+from __future__ import annotations
+
+import codecs
+import json
+import time
+from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Generic, Iterable, Mapping, Optional, Sequence, Tuple, TypeVar, Union
+
+import anyio
+import httpx
+
+from ._base import (
+    TERMINAL_JOB_EVENTS,
+    Config,
+    Route,
+    build_path,
+    build_query,
+    encode_body,
+    error_from_response,
+    idempotency_key,
+    is_json,
+    is_terminal_job,
+    job_failure,
+    job_id_of,
+    job_ops_for,
+    per_attempt_timeout,
+    request_headers,
+    retry_safe,
+    should_retry,
+)
+from ._errors import B3OSConnectionError, B3OSError, B3OSJobError, B3OSTimeoutError
+from ._ops import JobOps, Op
+from ._response import ResponseInfo, ResultDict, attach
+from ._sse import SSEDecoder, SSEMessage
+from ._sync import _CONNECT_ERRORS, _connect_refused
+from ._util import backoff, new_idempotency_key, parse_retry_after
+
+T = TypeVar("T")
+E = TypeVar("E")
+J = TypeVar("J")
+
+
+class AsyncPage(ResultDict, Generic[T]):
+    """One page of a list (a dict). `async for x in page.auto_paging_iter()` walks every item."""
+
+    __slots__ = ("_next",)
+    _next: Callable[[str], Any]
+
+    async def auto_paging_iter(self) -> AsyncIterator[T]:
+        page: AsyncPage[T] = self
+        while True:
+            for item in page.get("data", []):
+                yield item
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+            page = await page._next(cursor)
+
+
+class AsyncEventStream(Generic[E]):
+    """`async for ev in stream: ...`, once. Resumes after drops with Last-Event-ID where the stream allows it."""
+
+    def __init__(
+        self,
+        open_fn: Callable[[int, Optional[str], Any], Awaitable[httpx.Response]],
+        *,
+        first: Optional[httpx.Response] = None,
+        is_terminal: Optional[Callable[[Any], bool]] = None,
+        resumable: bool,
+        reconnect_on_end: bool = False,
+        max_reconnects: int = 6,
+        done_sentinel: bool = False,
+        operation_id: str = "",
+    ) -> None:
+        self._open = open_fn
+        self._first = first
+        self._is_terminal = is_terminal
+        self._resumable = resumable
+        self._reconnect_on_end = reconnect_on_end
+        self._max_reconnects = max_reconnects
+        self._done_sentinel = done_sentinel
+        self._op = operation_id
+        self._resp: Optional[httpx.Response] = None
+        self._closed = False
+        self._iterating = False
+        self.last_event_id: Optional[str] = None
+        self.last_event: Optional[E] = None
+        self.completed = False
+
+    async def aclose(self) -> None:
+        self._closed = True
+        r = self._resp or self._first
+        if r is not None:
+            await r.aclose()
+
+    async def __aenter__(self) -> "AsyncEventStream[E]":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    def _parse(self, msg: SSEMessage) -> Any:
+        try:
+            return json.loads(msg.data)
+        except ValueError as e:
+            raise B3OSError("invalid_response", detail=f"Could not parse the {msg.event} event: {e}", operation_id=self._op)
+
+    async def __aiter__(self) -> AsyncIterator[E]:
+        if self._iterating:
+            raise RuntimeError("b3os: an AsyncEventStream can be iterated only once")
+        self._iterating = True
+        attempt = 0
+        failures = 0
+        retry_ms: Optional[int] = None
+        while not self._closed:
+            if attempt == 0 and self._first is not None:
+                resp = self._first
+            else:
+                try:
+                    resp = await self._open(attempt, self.last_event_id, self.last_event)
+                except B3OSError as e:
+                    if attempt == 0 or not self._resumable or not (e.retryable or e.code == "connection_error"):
+                        raise
+                    failures += 1
+                    if failures > self._max_reconnects:
+                        raise B3OSError("stream_interrupted", detail=f"Reconnecting failed {failures} times", operation_id=self._op)
+                    attempt += 1
+                    await anyio.sleep((retry_ms / 1000) if retry_ms is not None else backoff(failures - 1, 0.5, 10))
+                    continue
+            self._resp = resp
+            decoder = SSEDecoder()
+            utf8 = codecs.getincrementaldecoder("utf-8")(errors="replace")
+            got = False
+            broken: Optional[BaseException] = None
+            idle = False
+            try:
+                async for chunk in resp.aiter_bytes():
+                    for msg in decoder.feed(utf8.decode(chunk)):
+                        if msg.retry is not None:
+                            retry_ms = msg.retry
+                        if msg.id is not None:
+                            self.last_event_id = msg.id
+                        if self._done_sentinel and msg.data.strip() == "[DONE]":
+                            self.completed = True
+                            return
+                        ev = self._parse(msg)
+                        got = True
+                        failures = 0
+                        self.last_event = ev
+                        terminal = bool(self._is_terminal and self._is_terminal(ev))
+                        if terminal:
+                            self.completed = True
+                        yield ev
+                        if terminal or self._closed:
+                            return
+            except httpx.ReadTimeout as e:
+                idle, broken = True, e
+            except (httpx.TransportError, httpx.StreamError) as e:
+                broken = e
+            finally:
+                await resp.aclose()
+            if self._closed:
+                return
+            if broken is not None:
+                if not self._resumable:
+                    raise B3OSError(
+                        "timeout" if idle else "stream_interrupted",
+                        detail=("No data within the idle timeout" if idle else f"The event stream broke: {broken}"),
+                        operation_id=self._op,
+                    )
+                failures += 1
+                if failures > self._max_reconnects:
+                    raise B3OSError("stream_interrupted", detail=f"The event stream broke {failures} times: {broken}", operation_id=self._op)
+            else:
+                if not self._resumable or not self._reconnect_on_end:
+                    return
+                if not got:
+                    failures += 1
+                    if failures > self._max_reconnects:
+                        raise B3OSError("stream_interrupted", detail="The event stream kept closing without events", operation_id=self._op)
+            attempt += 1
+            delay = (retry_ms / 1000) if retry_ms is not None else (0.0 if got else backoff(max(0, failures - 1), 0.5, 10))
+            if delay:
+                await anyio.sleep(delay)
+
+
+class AsyncJobEventStream(AsyncEventStream[E], Generic[E, J]):
+    def __init__(self, *args: Any, final_job: Callable[[Any], Awaitable[J]], **kw: Any) -> None:
+        super().__init__(*args, **kw)
+        self._final_job = final_job
+        self._result: Optional[J] = None
+
+    async def __aiter__(self) -> AsyncIterator[E]:
+        async for ev in super().__aiter__():
+            if isinstance(ev, dict) and ev.get("type") in TERMINAL_JOB_EVENTS:
+                self._result = await self._final_job(ev)
+            yield ev
+
+    @property
+    def result(self) -> Optional[J]:
+        return self._result
+
+    async def final(self) -> J:
+        if not self._iterating:
+            async for _ in self:
+                pass
+        if self._result is None:
+            raise B3OSError("stream_interrupted", detail="The event stream ended before the job finished", operation_id=self._op)
+        return self._result
+
+
+class AsyncCore:
+    def __init__(self, cfg: Config, on_response: Optional[Callable[[ResponseInfo], None]] = None, http_client: Optional[httpx.AsyncClient] = None) -> None:
+        self._cfg = cfg
+        self._on_response = on_response
+        self._clients: Dict[str, httpx.AsyncClient] = {}
+        self._shared = http_client
+
+    @property
+    def api_key(self) -> Optional[str]:
+        return self._cfg.api_key
+
+    @property
+    def routes(self) -> Dict[str, str]:
+        return {"node": self._cfg.node.label, "edge": self._cfg.edge.label, "node_kind": self._cfg.node.kind}
+
+    def _http(self, route: Route) -> httpx.AsyncClient:
+        if self._shared is not None and not route.uds:
+            return self._shared
+        c = self._clients.get(route.label)
+        if c is None:
+            transport = httpx.AsyncHTTPTransport(uds=route.uds) if route.uds else None
+            c = httpx.AsyncClient(transport=transport, follow_redirects=True, timeout=None)
+            self._clients[route.label] = c
+        return c
+
+    async def aclose(self) -> None:
+        for c in self._clients.values():
+            await c.aclose()
+        self._clients.clear()
+
+    async def _send(
+        self,
+        op: Op,
+        *,
+        path: Sequence[Union[str, int]] = (),
+        query: Optional[Mapping[str, Any]] = None,
+        header_params: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        body_type: Optional[str] = None,
+        accept: str = "application/json",
+        sse: bool = False,
+        extra_query: Optional[Mapping[str, str]] = None,
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> Tuple[httpx.Response, ResponseInfo]:
+        opts = dict(options or {})
+        path_str = build_path(op, path)
+        params = build_query(query, extra_query)
+        key = idempotency_key(op, opts)
+        streaming_body = hasattr(body, "__aiter__") or hasattr(body, "read")
+        safe = retry_safe(op, key, streaming_body)
+        max_retries = 0 if streaming_body else int(opts.get("max_retries", self._cfg.max_retries))
+        tmo = per_attempt_timeout(self._cfg, op, opts, sse)
+        route = self._cfg.route(op)
+        attempt = 0
+        while True:
+            headers = request_headers(self._cfg, route, op, opts, accept, header_params, key)
+            content = encode_body(op, body, body_type, headers)
+            client = self._http(route)
+            req = client.build_request(
+                op.method,
+                route.base + path_str,
+                params=httpx.QueryParams(params) if params else None,
+                headers=headers,
+                content=content,
+                timeout=httpx.Timeout(tmo, connect=min(tmo, 10.0)),
+            )
+            t0 = time.perf_counter()
+            try:
+                resp = await client.send(req, stream=True)
+            except httpx.TimeoutException as e:
+                if isinstance(e, httpx.ConnectTimeout) and attempt < max_retries:
+                    await anyio.sleep(backoff(attempt))
+                    attempt += 1
+                    continue
+                raise B3OSTimeoutError(f"{op.id} did not answer within {tmo} s ({route.label})", operation_id=op.id) from e
+            except httpx.TransportError as e:
+                if route.auto and _connect_refused(e):
+                    self._cfg.fall_back_to_edge()
+                    route = self._cfg.edge
+                    continue
+                if attempt < max_retries and (safe or isinstance(e, _CONNECT_ERRORS)):
+                    await anyio.sleep(backoff(attempt))
+                    attempt += 1
+                    continue
+                raise B3OSConnectionError(f"Could not reach {route.label}: {e}", operation_id=op.id) from e
+            info = ResponseInfo(
+                operation_id=op.id,
+                method=op.method,
+                url=(f"{route.label}{path_str}" if route.uds else str(resp.request.url)),
+                status=resp.status_code,
+                headers=resp.headers,
+                transport="uds" if route.uds else "http",
+                attempts=attempt + 1,
+                elapsed_ms=(time.perf_counter() - t0) * 1000,
+                idempotency_key=key,
+            )
+            if self._on_response:
+                try:
+                    self._on_response(info)
+                except Exception:
+                    pass
+            if 200 <= resp.status_code < 300 or resp.status_code == 101:
+                return resp, info
+            try:
+                text = (await resp.aread()).decode("utf-8", errors="replace")
+            except httpx.HTTPError:
+                text = ""
+            finally:
+                await resp.aclose()
+            err = error_from_response(self._cfg, route, op, resp.status_code, resp.headers, text)
+            if attempt < max_retries and should_retry(err, safe):
+                delay = err.retry_after if err.retry_after is not None else backoff(attempt)
+                if delay <= self._cfg.max_retry_delay:
+                    await anyio.sleep(delay)
+                    attempt += 1
+                    continue
+            raise err
+
+    async def _read(self, resp: httpx.Response, info: ResponseInfo, op: Op, expect: str) -> Any:
+        try:
+            if resp.status_code in (204, 101) or op.method == "HEAD":
+                return None
+            ct = resp.headers.get("content-type", "")
+            data = await resp.aread()
+        except httpx.TimeoutException as e:
+            raise B3OSTimeoutError(f"{op.id} body did not arrive in time", operation_id=op.id) from e
+        except httpx.TransportError as e:
+            raise B3OSConnectionError(f"The response body of {op.id} broke: {e}", operation_id=op.id) from e
+        finally:
+            await resp.aclose()
+        if expect == "bytes" or (expect == "auto" and not is_json(ct) and not ct.startswith("text/")):
+            return attach(bytes(data), info)
+        text = data.decode("utf-8", errors="replace")
+        if expect == "text" or (expect == "auto" and not is_json(ct)):
+            return attach(text, info)
+        if not text:
+            return None
+        try:
+            return attach(json.loads(text), info)
+        except ValueError as e:
+            raise B3OSError(
+                "invalid_response",
+                status=resp.status_code,
+                detail=f"{op.id} answered {resp.status_code} with a body that is not JSON ({ct or 'no content type'})",
+                request_id=resp.headers.get("x-request-id"),
+                operation_id=op.id,
+            ) from e
+
+    async def _call(self, op: Op, *, accept: str = "application/json", expect: str = "auto", **kw: Any) -> Any:
+        resp, info = await self._send(op, accept=accept, **kw)
+        return await self._read(resp, info, op, expect)
+
+    async def _list(self, op: Op, **kw: Any) -> AsyncPage[Any]:
+        data = await self._call(op, **kw)
+        page: AsyncPage[Any] = AsyncPage(data or {})
+        page._b3os_response = getattr(data, "_b3os_response", None)
+        query = dict(kw.get("query") or {})
+
+        async def nxt(cursor: str) -> AsyncPage[Any]:
+            kw2 = dict(kw)
+            kw2["query"] = {**query, "cursor": cursor}
+            return await self._list(op, **kw2)
+
+        page._next = nxt
+        return page
+
+    def _expect_sse(self, resp: httpx.Response, info: ResponseInfo, op: Op) -> httpx.Response:
+        ct = resp.headers.get("content-type", "")
+        if not ct.startswith("text/event-stream"):
+            raise B3OSError(
+                "invalid_response",
+                status=resp.status_code,
+                detail=f"{op.id} answered {resp.status_code} with {ct or 'no content type'} instead of an event stream",
+                request_id=info.request_id,
+                operation_id=op.id,
+            )
+        return resp
+
+    async def _open_get_stream(self, op: Op, kw: Mapping[str, Any], last_event_id: Optional[str], first_attempt: bool) -> httpx.Response:
+        opts = dict(kw.get("options") or {})
+        headers = dict(opts.get("extra_headers") or {})
+        if last_event_id is not None:
+            headers["last-event-id"] = last_event_id
+        opts["extra_headers"] = headers
+        if not first_attempt:
+            opts["max_retries"] = 0
+        resp, info = await self._send(op, accept="text/event-stream", sse=True, **{**kw, "options": opts})
+        try:
+            return self._expect_sse(resp, info, op)
+        except B3OSError:
+            await resp.aclose()
+            raise
+
+    async def _stream(self, op: Op, *, terminal: Optional[Callable[[Any], bool]] = None, reconnect_on_end: bool = False, last_event_id: Optional[str] = None, **kw: Any) -> AsyncEventStream[Any]:
+        first = await self._open_get_stream(op, kw, last_event_id, True)
+
+        async def reopen(attempt: int, lid: Optional[str], _ev: Any) -> httpx.Response:
+            return await self._open_get_stream(op, kw, lid, False)
+
+        return AsyncEventStream(reopen, first=first, is_terminal=terminal, resumable=True, reconnect_on_end=reconnect_on_end, operation_id=op.id)
+
+    async def _post_stream(self, op: Op, *, terminal: Optional[Callable[[Any], bool]] = None, done_sentinel: bool = False, **kw: Any) -> AsyncEventStream[Any]:
+        resp, info = await self._send(op, accept="text/event-stream", sse=True, **kw)
+        try:
+            first = self._expect_sse(resp, info, op)
+        except B3OSError:
+            await resp.aclose()
+            raise
+
+        async def reopen(attempt: int, lid: Optional[str], ev: Any) -> httpx.Response:
+            raise B3OSError("stream_interrupted", detail=f"{op.id} streams cannot resume", operation_id=op.id)
+
+        return AsyncEventStream(reopen, first=first, is_terminal=terminal, resumable=False, done_sentinel=done_sentinel, operation_id=op.id)
+
+    async def _final_job(self, ops: JobOps, ev: Mapping[str, Any]) -> Any:
+        job = ev.get("job")
+        if is_terminal_job(job):
+            return job
+        jid = ev.get("job_id")
+        if not isinstance(jid, str):
+            raise B3OSError("invalid_response", detail="terminal event without a job", operation_id=ops.events.id)
+        return await self._call(ops.get, path=[jid])
+
+    async def _job_events(self, ops: JobOps, job: Any, *, last_event_id: Optional[str] = None, options: Optional[Mapping[str, Any]] = None) -> AsyncJobEventStream[Any, Any]:
+        jid = job_id_of(job)
+        kw: Dict[str, Any] = {"path": [jid], "options": options or {}}
+        first = await self._open_get_stream(ops.events, kw, last_event_id, True)
+
+        async def reopen(attempt: int, lid: Optional[str], _ev: Any) -> httpx.Response:
+            return await self._open_get_stream(ops.events, kw, lid, False)
+
+        async def final(e: Any) -> Any:
+            return await self._final_job(ops, e)
+
+        return AsyncJobEventStream(
+            reopen,
+            first=first,
+            is_terminal=lambda e: isinstance(e, dict) and e.get("type") in TERMINAL_JOB_EVENTS,
+            resumable=True,
+            reconnect_on_end=True,
+            operation_id=ops.events.id,
+            final_job=final,
+        )
+
+    def _finish(self, job: Any, raise_on_failure: bool) -> Any:
+        if job.get("status") == "succeeded" or not raise_on_failure:
+            return job
+        raise B3OSJobError(job, **job_failure(job))
+
+    async def _wait_job(self, ops: JobOps, job: Any, *, timeout: Optional[float] = None, raise_on_failure: bool = True, on_event: Optional[Callable[[Any], None]] = None) -> Any:
+        if not isinstance(job, str) and is_terminal_job(job):
+            return self._finish(job, raise_on_failure)
+        jid = job_id_of(job)
+        budget = timeout if timeout is not None else ops.events.timeout_ms / 1000
+        deadline = time.monotonic() + budget
+        polling = False
+        poll_attempt = 0
+        while time.monotonic() < deadline:
+            if not polling:
+                try:
+                    remaining = max(1.0, deadline - time.monotonic())
+                    stream = await self._job_events(ops, jid, options={"timeout": min(remaining, 45.0)})
+                    async for ev in stream:
+                        if on_event:
+                            on_event(ev)
+                        if isinstance(ev, dict) and ev.get("type") in TERMINAL_JOB_EVENTS:
+                            return self._finish(await self._final_job(ops, ev), raise_on_failure)
+                        if time.monotonic() >= deadline:
+                            await stream.aclose()
+                            break
+                except B3OSError as e:
+                    if e.code in ("route_not_found", "not_implemented", "invalid_response") or e.status in (405, 406):
+                        polling = True
+                    elif e.status in (401, 403, 404, 410):
+                        raise
+                    elif not e.retryable and e.code not in ("stream_interrupted", "timeout"):
+                        raise
+            resp, info = await self._send(ops.get, path=[jid])
+            cur = await self._read(resp, info, ops.get, "json")
+            if is_terminal_job(cur):
+                return self._finish(cur, raise_on_failure)
+            ra = parse_retry_after(info.headers.get("retry-after"))
+            await anyio.sleep(max(0.0, min(deadline - time.monotonic(), ra if ra is not None else backoff(poll_attempt, 1.0, 5.0))))
+            poll_attempt += 1
+        raise B3OSTimeoutError(f"{jid} was not finished after {budget} s; it keeps running on the server", operation_id=ops.get.id)
+
+    async def _job(self, op: Op, *, wait: Union[bool, float] = False, stream: bool = False, raise_on_failure: bool = True, on_event: Optional[Callable[[Any], None]] = None, **kw: Any) -> Any:
+        assert op.job is not None
+        ops = op.job
+        opts = dict(kw.pop("options", None) or {})
+        if op.idem and not opts.get("idempotency_key"):
+            opts["idempotency_key"] = new_idempotency_key()
+        if stream:
+            resp, info = await self._send(op, accept="text/event-stream", sse=True, options=opts, **kw)
+            first = self._expect_sse(resp, info, op)
+
+            async def reopen(attempt: int, lid: Optional[str], ev: Any) -> httpx.Response:
+                jid = ev.get("job_id") if isinstance(ev, dict) else None
+                if not isinstance(jid, str):
+                    raise B3OSError("stream_interrupted", detail=f"{op.id}: the stream broke before the first event", operation_id=op.id)
+                return await self._open_get_stream(ops.events, {"path": [jid], "options": {}}, lid, False)
+
+            async def final(e: Any) -> Any:
+                return await self._final_job(ops, e)
+
+            return AsyncJobEventStream(
+                reopen,
+                first=first,
+                is_terminal=lambda e: isinstance(e, dict) and e.get("type") in TERMINAL_JOB_EVENTS,
+                resumable=True,
+                reconnect_on_end=True,
+                operation_id=op.id,
+                final_job=final,
+            )
+        if not wait:
+            return await self._call(op, options=opts, **kw)
+        budget = float(ops.events.timeout_ms / 1000 if wait is True else wait)
+        start = time.monotonic()
+        wait_s = int(max(0, min(60, budget)))
+        job = await self._call(op, extra_query={"wait": str(wait_s)}, options=opts, **kw)
+        remaining = budget - (time.monotonic() - start)
+        return await self._wait_job(ops, job, timeout=max(0.0, remaining), raise_on_failure=raise_on_failure, on_event=on_event)
+
+
+class AsyncJobs:
+    def __init__(
+        self,
+        core: AsyncCore,
+        table: Mapping[str, JobOps],
+        kinds: Optional[Mapping[str, JobOps]] = None,
+        generic_prefixes: Iterable[str] = (),
+    ) -> None:
+        self._core = core
+        self._table = table
+        self._kinds = kinds or {}
+        self._generic = frozenset(generic_prefixes)
+
+    def ops_for(self, job: Any) -> JobOps:
+        return job_ops_for(self._table, self._kinds, self._generic, job)
+
+    async def get(self, job: Any) -> Any:
+        return await self._core._call(self.ops_for(job).get, path=[job_id_of(job)])
+
+    async def wait(self, job: Any, *, timeout: Optional[float] = None, raise_on_failure: bool = True, on_event: Optional[Callable[[Any], None]] = None) -> Any:
+        return await self._core._wait_job(self.ops_for(job), job, timeout=timeout, raise_on_failure=raise_on_failure, on_event=on_event)
+
+    async def events(self, job: Any, *, last_event_id: Optional[str] = None) -> AsyncJobEventStream[Any, Any]:
+        return await self._core._job_events(self.ops_for(job), job, last_event_id=last_event_id)
+
+    async def cancel(self, job: Any) -> Any:
+        return await self._core._call(self.ops_for(job).cancel, path=[job_id_of(job)])