Client handles¶
Molq() uses a temporary stdio service. Pass endpoint and token for a shared
HTTP service. Wait durations and RPC timeouts are measured in seconds.
Destination binding¶
submit ¶
submit(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 |
|---|---|---|
Cluster |
Cluster
|
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 = submit("dev", "local", project_root="/absolute/project")
@local def hello(name): job = yield JobSpec.argv(["echo", name]) return job
Cluster decorator¶
Use local = submit("name", project_root="/shared/project") and @local. Yield a JobSpec to receive a
Job; the generator returns its own result. See the Python guide for complete examples.
__call__ ¶
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 Job. 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
Synchronous OOP projections of the public RPC contract.
Molq ¶
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 ¶
Close this client session without cancelling accepted allocations.
Returns:
| Name | Type | Description |
|---|---|---|
None |
None
|
This session's connection is released. |
rpc ¶
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 ¶
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 |
|---|---|---|
Cluster |
Cluster
|
A handle using this client's connection. |
job ¶
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 |
|---|---|---|
Job |
Job
|
A handle holding a shallow copy of the reference. |
jobs ¶
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 |
|---|---|---|
JobCollection |
JobCollection
|
A handle holding a copy of each reference. |
ClusterRegistry ¶
RPC-only access to durable destination definitions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
molq
|
Molq
|
Client used for registry operations. |
required |
register ¶
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 |
|---|---|---|
Cluster |
Cluster
|
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. |
Cluster ¶
A destination handle whose operations use public RPC.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
molq
|
Molq
|
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 ¶
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 ¶
Answer one SSH authentication prompt without storing the response.
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 ¶
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 ¶
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
|
Cluster resolution or the revision check fails, or the RPC fails with a potentially unknown mutation outcome. |
submit ¶
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 |
|---|---|
Job | JobCollection
|
Job | JobCollection: 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 ¶
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
|
Cluster
|
Destination that receives the copy. |
required |
destination_path
|
str
|
Path on |
required |
*options
|
str
|
rsync options passed unchanged, each one word with
any value attached ( |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
dict |
dict
|
Runtime transfer result. |
Raises:
| Type | Description |
|---|---|
MolqError
|
|
Example
local.transfer("/src/", hpc, "/scratch/project/", "-a", "--exclude=build/")
validate ¶
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 ¶
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 ¶
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 ¶
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 ¶
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. |
Job ¶
One allocation whose lifecycle interpretation is returned by the runtime.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
molq
|
Molq
|
Client used for allocation operations. |
required |
ref
|
dict
|
Registry-qualified reference, copied into this handle. |
required |
status ¶
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 ¶
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 ¶
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 ¶
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 ¶
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. |
JobCollection ¶
Batch operations sharing the runtime's collection completion semantics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
molq
|
Molq
|
Client used for batch operations. |
required |
refs
|
list[dict]
|
Allocation references; each is copied into this handle. |
required |
status ¶
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 ¶
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 ¶
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 ¶
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)