Skip to content

Async handles

Await decorated calls and operations that contact the service; close with await local.close() or await mq.close(). The API mirrors the synchronous handles. Request values are shared.

Destination binding

asubmit async

asubmit(cluster_name, cluster_type=None, *, project_root=None, endpoint=None, registry=None, config=None, token=None, timeout=130, registry_id=None, **definition)

Bind a destination for @destination and yield JobSpec submission.

Parameters:

Name Type Description Default
cluster_name str

Registered destination name or ID.

required
cluster_type str | None

Scheduler for an explicit destination binding: local (Shell), shell, slurm, pbs or lsf. None selects an existing one.

None
project_root Path | Path | str | None

Target directory used by decorated submissions.

None
endpoint str | None

HTTP(S) service endpoint; None uses temporary stdio.

None
registry Path | str | None

Registry for temporary stdio.

None
config Path | str | None

Settings file for temporary stdio.

None
token str | None

HTTP bearer credential.

None
timeout float

Per-RPC response deadline in seconds.

130
registry_id str | None

Expected registry identity.

None
**definition Any

Destination fields such as transport, defaults and launcher. New local destinations default to local transport. Existing bindings must match the supplied fields.

{}

Returns:

Name Type Description
AsyncCluster AsyncCluster

Callable destination owning its connection. Call close() when finished. Selecting by name alone is lazy; explicit binding uses RPC.

Raises:

Type Description
MolqError

The definition conflicts, is invalid or an RPC fails. An uncertain registration or submission is never automatically resent.

Example

local = await asubmit("dev", "local", project_root="/absolute/project")

@local def hello(name): job = yield JobSpec.argv(["echo", name]) return job

Cluster decorator

Decorate a synchronous request builder with an AsyncCluster and await the decorated call. Yield a JobSpec; each yield receives an AsyncJob.

__call__

__call__(function)

Submit each yielded JobSpec and preserve the function's return.

Parameters:

Name Type Description Default
function Callable

Synchronous function or generator. Each yielded JobSpec receives its submitted AsyncJob. Ordinary functions return their result without submitting.

required

Returns:

Name Type Description
Callable Callable

A function with the original signature and metadata. A generator returns its own result. Decoration performs no RPC. The client owns connection lifetime.

Raises:

Type Description
TypeError

The function is async or is not callable.

MolqError

A request is not a JobSpec, or submission fails; the error propagates without resend.

Example

@local # Bound with project_root. def hello(name): job = yield JobSpec.argv(["echo", name]) return job

Generated async OOP projection; edit objects.py and regenerate.

AsyncMolq

AsyncMolq(*, endpoint=None, registry=None, config=None, token=None, timeout=130, registry_id=None)

Connect to one Runtime; absent endpoint uses its temporary stdio form.

Parameters:

Name Type Description Default
endpoint str | None

HTTP(S) endpoint; None selects temporary stdio serve.

None
registry Path | str | None

Registry path for a temporary stdio session.

None
config Path | str | None

Configuration file for temporary stdio serve.

None
token str | None

Bearer credential for the HTTP endpoint.

None
timeout float

Per-RPC response deadline in seconds.

130
registry_id str | None

Expected registry identity, checked on connection.

None

Connection is lazy unless the client is entered as a context manager. RPC methods raise MolqError for structured runtime and connection failures. A dispatched mutation with an unknown outcome must be reconciled before resend.

close async

close()

Close this client session without cancelling accepted allocations.

Returns:

Name Type Description
None None

This session's connection is released.

rpc async

rpc(method, **params)

Call any named operation in the public RPC contract.

Parameters:

Name Type Description Default
method str

Public method name, such as "jobs.get_many".

required
**params Any

Named parameters; None values are omitted and local Value instances are converted to wire dictionaries.

{}

Returns:

Name Type Description
Any Any

The runtime's method-specific result.

Raises:

Type Description
MolqError

The runtime rejects the request or the connection fails; dispatched mutation failures may have outcome "unknown".

cluster

cluster(name, *, project_root=None)

Construct a handle without querying the destination.

Parameters:

Name Type Description Default
project_root Path | Path | str | None

Optional target directory for submissions.

None
name str

Registered cluster name or ID, resolved by the runtime.

required

Returns:

Name Type Description
AsyncCluster AsyncCluster

A handle using this client's connection.

job

job(ref)

Construct a handle to a registry-qualified native allocation.

Parameters:

Name Type Description Default
ref dict

JobRef with registry_id, cluster_id, native_id and incarnation.

required

Returns:

Name Type Description
AsyncJob AsyncJob

A handle holding a shallow copy of the reference.

jobs

jobs(refs)

Construct a handle for batch operations on saved references.

Parameters:

Name Type Description Default
refs list[dict]

Registry-qualified native allocation references.

required

Returns:

Name Type Description
AsyncJobCollection AsyncJobCollection

A handle holding a copy of each reference.

AsyncClusterRegistry

AsyncClusterRegistry(molq)

RPC-only access to durable destination definitions.

Parameters:

Name Type Description Default
molq AsyncMolq

Client used for registry operations.

required

register async

register(**definition)

Register an explicit destination definition.

Parameters:

Name Type Description Default
**definition Any

Canonical cluster fields, including name, scheduler, and transport, plus required transport/site settings.

{}

Returns:

Name Type Description
AsyncCluster AsyncCluster

A handle using the new cluster's stable ID.

Raises:

Type Description
MolqError

The definition is invalid, conflicts with the registry, or the RPC fails; a disconnected mutation may have applied.

list async

list()

List destination definitions without querying native job state.

Returns:

Type Description
list[dict]

list[dict]: Runtime-owned definitions with stable IDs and revisions.

Raises:

Type Description
MolqError

The registry request or RPC connection fails.

AsyncCluster

AsyncCluster(molq, name, *, project_root=None)

A destination handle whose operations use public RPC.

Parameters:

Name Type Description Default
molq AsyncMolq

Client used for destination operations.

required
name str

Registered destination name or ID.

required
project_root Path | Path | str | None

Optional project path for submissions through this handle.

None

close async

close()

Release this destination's client connection, leaving jobs running.

Returns:

Name Type Description
None None

The connection is released, including other handles sharing it.

authenticate async

authenticate(code)

Answer one SSH authentication prompt without storing the response.

definition async

definition()

Read the runtime-owned definition and revision.

Returns:

Name Type Description
dict dict

The canonical cluster definition and current revision.

Raises:

Type Description
MolqError

The cluster cannot be resolved or the RPC fails.

update async

update(definition, *, expected_revision)

Replace destination configuration with a revision check.

Parameters:

Name Type Description Default
definition dict

Complete canonical destination definition.

required
expected_revision int

Revision returned by the most recent read.

required

Returns:

Name Type Description
dict dict

The runtime's updated definition and revision.

Raises:

Type Description
MolqError

Validation, cluster resolution or the revision check fails, or the RPC fails with a potentially unknown mutation outcome.

remove async

remove(*, expected_revision)

Remove a destination definition without cancelling native jobs.

Parameters:

Name Type Description Default
expected_revision int

Revision returned by the most recent read.

required

Returns:

Name Type Description
dict dict

The runtime's removal result.

Raises:

Type Description
MolqError

AsyncCluster resolution or the revision check fails, or the RPC fails with a potentially unknown mutation outcome.

submit async

submit(spec, *, project_root=None, request_key=None)

Submit one allocation or a native array.

Parameters:

Name Type Description Default
spec JobSpec

Immutable allocation specification.

required
project_root Path | Path | str | None

Existing target directory. Defaults to the project bound when this handle was created.

None
request_key str | None

Optional durable key. Repeating the same request reconciles the prior submission without resending it.

None

Returns:

Type Description
AsyncJob | AsyncJobCollection

AsyncJob | AsyncJobCollection: One allocation or the accepted array elements.

Raises:

Type Description
MolqError

The request is not a JobSpec, the runtime or native scheduler rejects the request, or the RPC fails. An unknown mutation outcome may mean the allocation was already accepted.

Example

job = cluster.submit( JobSpec.argv(["python", "work.py"]), project_root="/absolute/project" )

transfer async

transfer(source_path, destination, destination_path, *options, timeout=90)

Copy a path from this destination to another with one rsync run.

Parameters:

Name Type Description Default
source_path str

Path on this destination. A relative path is relative to the login home; a trailing slash is passed to rsync.

required
destination AsyncCluster

Destination that receives the copy.

required
destination_path str

Path on destination.

required
*options str

rsync options passed unchanged, each one word with any value attached ("--exclude=build/"). Nothing is implied.

()

Returns:

Name Type Description
dict dict

Runtime transfer result. outcome is applied when the copy finishes; output is rsync's standard output.

Raises:

Type Description
MolqError

destination is not a AsyncCluster, a path or option is rejected, or the copy fails. An unknown mutation outcome may mean the destination was already changed.

Example

local.transfer("/src/", hpc, "/scratch/project/", "-a", "--exclude=build/")

validate async

validate(spec)

Validate schema and exact native representation through the runtime.

Parameters:

Name Type Description Default
spec JobSpec

Allocation specification to validate.

required

Returns:

Name Type Description
dict dict

Runtime validation result; it does not prove resource availability or scheduling permission on the target.

Raises:

Type Description
MolqError

The specification is invalid, cannot be represented, or the RPC fails.

preview async

preview(spec, *, project_root=None)

Preview an allocation using the scheduler's submission renderer.

Parameters:

Name Type Description Default
spec JobSpec

Allocation specification to render.

required
project_root Path | Path | str | None

Existing target directory or the bound project.

None

Returns:

Name Type Description
dict dict

Runtime-rendered submission content without a native submission.

Raises:

Type Description
MolqError

The specification is invalid, cannot be represented, or the RPC fails.

list async

list(*, states=None, name=None, project_root=None)

Query the target account's native queue.

Parameters:

Name Type Description Default
states list[str] | None

Canonical states to select; None selects all.

None
name str | None

Exact native job name to select.

None
project_root Path | Path | str | None

Project to list for Shell destinations.

None

Returns:

Name Type Description
dict dict

Canonical snapshots with query coverage and freshness metadata.

Raises:

Type Description
MolqError

The filters are invalid, the native query fails, or the RPC fails.

history async

history(*, refs=None, since=None, until=None, states=None, name=None, limit=None)

Query refs or account history by RFC3339 ended-at window.

Parameters:

Name Type Description Default
refs list[dict] | None

Explicit refs; excludes every range filter.

None
since str | None

Inclusive RFC3339 ended-at lower bound, defaulting to until minus 24 hours.

None
until str | None

Exclusive RFC3339 upper bound, defaulting to the runtime's current UTC time.

None
states list[str] | None

Canonical terminal states to select; None selects all terminal states.

None
name str | None

Exact native job name to select.

None
limit int | None

Result bound; defaults to 100 and is at most 1024.

None

Returns:

Name Type Description
dict dict

Native history snapshots with coverage and freshness metadata.

Raises:

Type Description
MolqError

Filters are invalid, history is unavailable or unsupported, or the RPC fails.

observe async

observe(*, cursor=None, project_root=None)

Request one cluster sample and its runtime-owned diff.

Parameters:

Name Type Description Default
cursor str | None

Cursor from a previous observation of this scope; None establishes a baseline.

None
project_root Path | Path | str | None

Project to observe for Shell destinations.

None

Returns:

Name Type Description
dict dict

Snapshots, changes, completion and the next cursor. A missing or expired baseline is reported as a resynchronization.

Raises:

Type Description
MolqError

The cluster sample or RPC fails.

AsyncJob

AsyncJob(molq, ref)

One allocation whose lifecycle interpretation is returned by the runtime.

Parameters:

Name Type Description Default
molq AsyncMolq

Client used for allocation operations.

required
ref dict

Registry-qualified reference, copied into this handle.

required

status async

status(*, consistency='live', max_age=5)

Read canonical allocation observations through the runtime.

Parameters:

Name Type Description Default
consistency str

"live" queries native state, "bounded" may use a sufficiently fresh cache entry, and "cached" only reads the cache.

'live'
max_age float

Maximum cache age in seconds for bounded consistency.

5

Returns:

Name Type Description
dict dict

A one-snapshot collection with runtime completion, coverage and freshness metadata.

Raises:

Type Description
MolqError

References or consistency arguments are invalid, required cached data is missing, or the RPC fails.

requeue async

requeue()

Ask Slurm to restart this incomplete job or array element.

Returns:

Name Type Description
dict dict

Native acceptance and the reference used for the request.

cancel async

cancel(*, request_key=None)

Request cancellation and return the native request outcome.

Parameters:

Name Type Description Default
request_key str | None

Optional bounded deduplication key within this serve instance.

None

Returns:

Name Type Description
dict dict

Cancellation outcome; acceptance does not confirm terminal state.

Raises:

Type Description
MolqError

The reference is invalid, native cancellation fails, or the RPC fails with a potentially unknown mutation outcome.

wait async

wait(*, timeout=3600, interval=1)

Sample until the runtime confirms this allocation is terminal.

Parameters:

Name Type Description Default
timeout float

Positive foreground wait deadline in seconds.

3600
interval float

Positive pause between samples in seconds.

1

Returns:

Name Type Description
dict dict

The collection observation confirming terminal completion.

Raises:

Type Description
MolqError

Arguments are invalid, an observation fails, or the wait deadline expires with kind WAIT_TIMEOUT. Expiration preserves the native allocation; each in-flight RPC has its own deadline.

logs async

logs(*, stream='stdout', offset=0, limit=262144)

Read a finite target log chunk through the runtime.

Parameters:

Name Type Description Default
stream str

"stdout" or "stderr".

'stdout'
offset int

Nonnegative byte offset in the selected log.

0
limit int

Maximum bytes to read, up to 262144.

262144

Returns:

Name Type Description
dict dict

Log text, next_offset and bytes_read for this chunk.

Raises:

Type Description
MolqError

The reference or range is invalid, the target file cannot be read, or the RPC fails.

AsyncJobCollection

AsyncJobCollection(molq, refs)

Batch operations sharing the runtime's collection completion semantics.

Parameters:

Name Type Description Default
molq AsyncMolq

Client used for batch operations.

required
refs list[dict]

Allocation references; each is copied into this handle.

required

status async

status(*, consistency='live', max_age=5)

Read canonical allocation observations through the runtime.

Parameters:

Name Type Description Default
consistency str

"live" queries native state, "bounded" may use a sufficiently fresh cache entry, and "cached" only reads the cache.

'live'
max_age float

Maximum cache age in seconds for bounded consistency.

5

Returns:

Name Type Description
dict dict

Canonical snapshots with runtime completion, coverage and freshness metadata.

Raises:

Type Description
MolqError

References or consistency arguments are invalid, or the RPC fails. Per-reference failures, including CACHE_MISS, are returned in query coverage.

cancel async

cancel()

Request cancellation of this collection in cluster batches.

Returns:

Name Type Description
dict dict

Explicit per-item cancellation outcomes and failures. Accepted cancellation requests do not confirm terminal completion.

Raises:

Type Description
MolqError

The batch request is invalid or the RPC fails with a potentially unknown mutation outcome.

observe async

observe(*, cursor=None)

Request one runtime-owned diff and collection completion result.

Parameters:

Name Type Description Default
cursor str | None

Cursor from a previous observation of these refs; None establishes a baseline.

None

Returns:

Name Type Description
dict dict

Snapshots, changes, runtime completion and the next cursor. Baseline loss is reported as a resynchronization.

Raises:

Type Description
MolqError

The batch request is invalid or the RPC fails.

wait async

wait(*, timeout=3600, interval=1)

Sample until every reference has confirmed terminal state.

Parameters:

Name Type Description Default
timeout float

Positive foreground wait deadline in seconds.

3600
interval float

Positive pause between samples in seconds.

1

Returns:

Name Type Description
dict dict

The observation with all_confirmed_terminal set by the runtime.

Raises:

Type Description
MolqError

Arguments are invalid, an observation fails, or the wait deadline expires with kind WAIT_TIMEOUT. Expiration preserves native allocations; each in-flight RPC has its own deadline.

Example

result = collection.wait(timeout=60, interval=2)