rebase.task

Signature

rb.task(
    name: str,
    *,
    key: str | None = None,
    parameters: dict[str, Any] | None = None,
) -> rb.Task

rb.task(...) returns a synchronous and asynchronous context manager. It reports the body as a named unit of work on the active run; it does not move the body to another worker or add retries.

with rb.task("Capture SE3", key="SE3", parameters={"zone": "SE3"}) as task:
    rows = capture("SE3")
    task.set_result({"outcome": "captured", "rows": rows})

Parameters

Parameter	Description
`name`	Required human-readable task name.
`key`	Optional caller-defined logical key.
`parameters`	Optional JSON object describing this unit's inputs.

Lifecycle

Entering reports running.
Normal exit reports succeeded.
Exceptional exit reports failed, including the exception type and message, then re-raises the workload exception.
task.set_result(value) records an optional JSON-object result while the context is active.

Catch exceptions outside the context when later tasks should continue. Raise after the remaining work if the overall run should also fail.

The returned Task exposes id, name, key, parameters, status, result, and error fields. id is None during local execution.

Async Context

async with rb.task("Fetch weather", parameters={"site": "ARN"}) as task:
    rows = await fetch_weather("ARN")
    task.set_result({"rows": rows})

The reporting calls are moved off the event loop. The workload body remains yours to await or execute.

rb.task itself is inline. For I/O-bound concurrency in one container, create one task inside each ThreadPoolExecutor worker and submit the worker through a fresh contextvars.copy_context() snapshot. This preserves the hosted run's request-local identity in that thread.

For platform fan-out, deploy the unit as a function and call Function.map inside a workflow step. Map items are recorded as tasks automatically; do not add an rb.task wrapper merely to obtain task rows.

See Tasks and Artifacts for complete sequential, thread-pool, and Function.map examples.

Errors and Local Execution

TaskReportingError is raised if a hosted run cannot start or finalize the task record. Outside a hosted run, the task validates its arguments and behaves as an in-memory context manager without API requests.