Apothic Client Functions and Jobs Reference#

This page covers the invocation surface for deployed functions and the job objects returned by background execution.

`Function`#

Function is the handle returned by local decorators such as @app.function(...), @app.endpoint(...), and the service decorators.

Lookup helper#

Function.from_name(
    app_name: str,
    function_name: str,
    *,
    client: ControlPlaneClient | None = None,
    base_url: str | None = None,
) -> RemoteFunction

Properties#

fn.name -> str
fn.options -> FunctionOptions
fn.kind -> str
fn.schedule -> Cron | Period | None
fn.service_url -> str | None
fn.aio -> async function API

Methods#

fn.spawn(*args, **kwargs) -> Job
fn.remote(*args, **kwargs) -> Any
fn.remote_gen(*args, **kwargs)
fn.remote_events(*args, snapshot: bool = False, event_types: list[str] | tuple[str, ...] | None = None, **kwargs)
fn.spawn_map(items: Iterable[Any]) -> list[Job]
fn.map(items: Iterable[Any]) -> list[Any]
fn.starmap(items: Iterable[Any]) -> list[Any]
fn.for_each(items: Iterable[Any]) -> None
fn.get_web_url() -> str

Async helper:

await fn.aio.get_web_url() -> str

`RemoteFunction`#

RemoteFunction is the lookup-first handle you use when you already know the deployed app and function names.

Lookup#

RemoteFunction.from_name(
    app_name: str,
    function_name: str,
    *,
    client: ControlPlaneClient | None = None,
    base_url: str | None = None,
) -> RemoteFunction

Properties#

remote.function_id -> str
remote.name -> str
remote.kind -> str
remote.service_url -> str | None
remote.schedule -> Cron | Period | None
remote.timeout_s -> int
remote.retries -> Retries | None
remote.concurrency -> ConcurrencySpec | None
remote.batching -> BatchingSpec | None
remote.app_name -> str | None
remote.aio -> async function API

Methods#

remote.spawn(*args, **kwargs) -> Job
remote.remote(*args, timeout_s: float = 600.0, **kwargs) -> Any
remote.remote_gen(*args, timeout_s: float = 600.0, **kwargs)
remote.remote_events(*args, snapshot: bool = False, event_types: list[str] | tuple[str, ...] | None = None, **kwargs)
remote.spawn_map(items: Iterable[Any]) -> list[Job]
remote.map(items: Iterable[Any], *, timeout_s: float = 600.0) -> list[Any]
remote.starmap(items: Iterable[Any], *, timeout_s: float = 600.0) -> list[Any]
remote.for_each(items: Iterable[Any], *, timeout_s: float = 600.0) -> None
remote.get_web_url() -> str

Async helper:

await remote.aio.get_web_url() -> str

`Job`#

Constructor#

Job(job_id: str, client: ControlPlaneClient)

Properties#

job.job_id -> str
job.aio -> async job API

Basic lifecycle methods#

job.status() -> str
job.logs() -> list[str]
job.cancel() -> str
job.wait(*, poll_interval_s: float = 1.0, timeout_s: float = 600.0) -> Any
job.wait_gen(
    *,
    poll_interval_s: float = 1.0,
    timeout_s: float = 600.0,
    checkpoint: JobStreamCheckpoint | None = None,
    cursor: JobStreamCursor | None = None,
    last_index: int | None = None,
    on_reset: str = "raise",
)

Async mirrors:

await job.aio.status() -> str
await job.aio.logs() -> list[str]
await job.aio.cancel() -> str
await job.aio.wait(...) -> Any
job.aio.wait_gen(...)

Job event streams#

Streaming methods#

job.stream_events(
    *,
    checkpoint: JobStreamCheckpoint | None = None,
    cursor: JobStreamCursor | None = None,
    last_index: int | None = None,
    event_types: list[str] | tuple[str, ...] | None = None,
)

job.watch(
    *,
    snapshot: bool = False,
    checkpoint: JobStreamCheckpoint | None = None,
    cursor: JobStreamCursor | None = None,
    last_index: int | None = None,
    event_types: list[str] | tuple[str, ...] | None = None,
)

job.checkpoint(
    *,
    cursor: JobStreamCursor | None = None,
    last_index: int | None = None,
    event_types: list[str] | tuple[str, ...] | None = None,
) -> JobStreamCheckpoint

Async mirrors:

job.aio.stream_events(...)
job.aio.watch(...)

Event type names#

Supported event_types values:

job.log
job.stream_item
job.status
job.result
job.error
job.end
job.reset
job.snapshot

Stream helper types#

JobStreamCursor(last_index: int = -1)
JobStreamCheckpoint(job_id: str, last_index: int = -1, event_types: tuple[str, ...] = ())
JobStreamEvent(event: str, data: Any, index: int | None = None)
JobLogEvent
JobStreamItemEvent
JobStatusEvent
JobResultEvent
JobErrorEvent
JobEndEvent
JobResetEvent
JobStreamResetError

Generator-returning functions#

When a function yields items instead of returning one final value:

remote_gen(...) yields the result items directly
wait_gen(...) consumes the job stream or polling fallback and yields the items

If the stream window rotates past the caller’s resume point, the runtime can emit a structured reset event. That is why wait_gen(...) exposes an on_reset policy.

Service URLs#

Service-shaped Function and RemoteFunction handles expose:

fn.service_url -> str | None
fn.get_web_url() -> str
await fn.aio.get_web_url() -> str