jobs¶

Client API for jobs in Nexus.

class qnexus.client.jobs.HybridStrategy( wait_for_status: JobStatusEnum = JobStatusEnum.COMPLETED, initial_interval: float = 1.0, max_interval_queued: float = 1200.0, max_interval_running: float = 180.0, backoff_factor: float = 2.0, websocket_timeout: float = 600.0, )[source]¶

Start with websocket, fall back to polling.

Recommended for most use cases.

websocket_timeout¶

How long to use websocket before switching to polling.

Type:: float

async get_status( job: JobRef, ) → JobStatus[source]¶

Use websocket for initial period, then fall back to polling.

Parameters:

job – The job to monitor.
wait_for_status – The status to wait for.
strategy – Hybrid strategy configuration.

Returns:

The final JobStatus when the target status is reached or job terminates.

class qnexus.client.jobs.PollingStrategy( wait_for_status: JobStatusEnum = JobStatusEnum.COMPLETED, initial_interval: float = 1.0, max_interval_queued: float = 1200.0, max_interval_running: float = 180.0, backoff_factor: float = 2.0, )[source]¶

Use exponential backoff polling.

More robust for long-running jobs (>10 minutes).

initial_interval¶

Starting poll interval in seconds.

Type:: float

max_interval_queued¶

Maximum poll interval when job is queued.

Type:: float

max_interval_running¶

Maximum poll interval when job is running/submitted.

Type:: float

backoff_factor¶

Multiplier for interval after each poll.

Type:: float

async get_status( job: JobRef, ) → JobStatus[source]¶

Poll job status with exponential backoff and adaptive intervals.

Uses different maximum poll intervals based on job state: - QUEUED: Polls less frequently (default 20 min) since queue position changes slowly - RUNNING/SUBMITTED: Polls more frequently (default 3 min) for responsiveness

Parameters:

job – The job to monitor.
wait_for_status – The status to wait for.
strategy – Polling configuration.

Returns:

The final JobStatus when the target status is reached or job terminates.

enum qnexus.client.jobs.RemoteRetryStrategy( value, )[source]¶

Strategy to use when retrying jobs.

Each strategy defines how the system should approach resolving potential conflicts with remote state.

FULL_RESTART will act as though the job is entirely fresh and re-perform every action.

Member Type:: str

Valid values are as follows:

FULL_RESTART = <RemoteRetryStrategy.FULL_RESTART: 'FULL_RESTART'>¶

class qnexus.client.jobs.WaitStrategy( wait_for_status: qnexus.models.job_status.JobStatusEnum = <JobStatusEnum.COMPLETED: 'COMPLETED'>, )[source]¶

class qnexus.client.jobs.WebsocketStrategy( wait_for_status: JobStatusEnum = JobStatusEnum.COMPLETED, )[source]¶

Use a websocket connection for real-time updates.

Best for short-running jobs (<10 minutes).

async get_status( job: JobRef, ) → JobStatus[source]¶: Check the Status of a Job via a websocket connection. Will use SSO tokens.

qnexus.client.jobs.cancel( job: JobRef, scope: ScopeFilterEnum = ScopeFilterEnum.USER, ) → None[source]¶

Attempt cancellation of a job in Nexus.

If the job has been submitted to a backend, Nexus will request cancellation of the job.

Examples

>>> import qnexus as qnx
>>> qnx.jobs.cancel(job_ref)

qnexus.client.jobs.cost( job: CompileJobRef | ExecuteJobRef, scope: ScopeFilterEnum = ScopeFilterEnum.USER, ) → float[source]¶

Get the HQC cost of a job from a JobRef.

Examples

>>> import qnexus as qnx
>>> hqc_cost = qnx.jobs.cost(job_ref)

qnexus.client.jobs.cost_confidence( job: CompileJobRef | ExecuteJobRef, scope: ScopeFilterEnum = ScopeFilterEnum.USER, ) → list[tuple[float, float]][source]¶

Get the HQC cost and confidence of a job from a JobRef.

Returns a list of tuples of (cost, confidence) for each job item.

qnexus.client.jobs.delete( job: JobRef, scope: ScopeFilterEnum = ScopeFilterEnum.USER, ) → None[source]¶

Delete a job in Nexus.

Examples

>>> import qnexus as qnx
>>> qnx.jobs.delete(job_ref)

Get a single job using filters. Throws an exception if the filters do not match exactly one object.

Examples

>>> import qnexus as qnx
>>> job_ref = qnx.jobs.get(name="my_compile_job", project=project_ref)

Get a NexusIterator over jobs with optional filters.

Examples

>>> import qnexus as qnx
>>> all_jobs = qnx.jobs.get_all(project=project_ref)
>>> all_jobs.df()

>>> from qnexus.models.job_status import JobStatusEnum
>>> errored = qnx.jobs.get_all(
...     project=project_ref,
...     job_status=[JobStatusEnum.ERROR],
... )

qnexus.client.jobs.results( job: CompileJobRef, allow_incomplete: bool = False, scope: ScopeFilterEnum = ScopeFilterEnum.USER, ) → DataframableList[CompilationResultRef | IncompleteJobItemRef][source]¶

qnexus.client.jobs.results( job: ExecuteJobRef, allow_incomplete: bool = False, scope: ScopeFilterEnum = ScopeFilterEnum.USER, ) → DataframableList[ExecutionResultRef | IncompleteJobItemRef]

Get the ResultRefs from a JobRef, if the job is complete. To enable fetching results from Jobs with incomplete items, set allow_incomplete=True.

Examples

>>> import qnexus as qnx
>>> compile_results = qnx.jobs.results(compile_job_ref)
>>> for result in compile_results:
...     compiled_circuit = result.get_output()

>>> execute_results = qnx.jobs.results(execute_job_ref)
>>> for result in execute_results:
...     backend_result = result.download_result()

qnexus.client.jobs.retry_submission( job: JobRef, retry_status: list[JobStatusEnum] | None = None, remote_retry_strategy: RemoteRetryStrategy = RemoteRetryStrategy.FULL_RESTART, user_group: str | None = None, ) → None[source]¶

Retry a job in Nexus according to status(es) or retry strategy.

By default, jobs with the ERROR status will be retried.

Examples

>>> import qnexus as qnx
>>> qnx.jobs.retry_submission(job_ref)

>>> from qnexus.models.job_status import JobStatusEnum
>>> qnx.jobs.retry_submission(
...     job_ref,
...     retry_status=[JobStatusEnum.ERROR, JobStatusEnum.CANCELLED],
... )

qnexus.client.jobs.status( job: JobRef, scope: ScopeFilterEnum = ScopeFilterEnum.USER, ) → JobStatus[source]¶

Get the status of a job.

Examples

>>> import qnexus as qnx
>>> job_status = qnx.jobs.status(job_ref)
>>> job_status.status
<JobStatusEnum.COMPLETED: 'COMPLETED'>

qnexus.client.jobs.wait_for( job: JobRef, wait_for_status: JobStatusEnum = JobStatusEnum.COMPLETED, timeout: float | None = None, strategy: WaitStrategy | None = None, ) → JobStatus[source]¶

Check job status until the job is complete (or a specified status).

Parameters:

job – The job to monitor.
wait_for_status – The status to wait for (default: COMPLETED).
timeout – Overall timeout in seconds. None for no timeout (default: None).
strategy –
How to monitor the job: - WebsocketStrategy(): Real-time updates via websocket.

Best for short jobs (<10 minutes).
- PollingStrategy(): Exponential backoff polling. Robust for long jobs (>10 minutes).
- HybridStrategy(): Websocket first, then polling fallback (default). Recommended for most use cases.

Returns:

The final JobStatus.

Raises:

JobError – If the job errors, is cancelled, depleted, or terminated (unless that was the status being waited for).
asyncio.TimeoutError – If the overall timeout is exceeded.

Examples

>>> import qnexus as qnx
>>> from qnexus.client.jobs import PollingStrategy, HybridStrategy

>>> # Use defaults (hybrid strategy)
>>> qnx.jobs.wait_for(job_ref)

>>> # Custom polling configuration
>>> qnx.jobs.wait_for(
...     job_ref,
...     strategy=PollingStrategy(initial_interval=5.0, backoff_factor=1.5),
... )

>>> # Custom hybrid with polling fallback config
>>> qnx.jobs.wait_for(
...     job_ref,
...     strategy=HybridStrategy(
...         websocket_timeout=300.0,
...         polling=PollingStrategy(max_interval_running=60.0),
...     ),
... )

enum qnexus.jobs.JobStatusEnum( value, )[source]¶

Possible job statuses

Member Type:: str

Valid values are as follows:

COMPLETED = <JobStatusEnum.COMPLETED: 'COMPLETED'>¶

QUEUED = <JobStatusEnum.QUEUED: 'QUEUED'>¶

SUBMITTED = <JobStatusEnum.SUBMITTED: 'SUBMITTED'>¶

RUNNING = <JobStatusEnum.RUNNING: 'RUNNING'>¶

CANCELLED = <JobStatusEnum.CANCELLED: 'CANCELLED'>¶

ERROR = <JobStatusEnum.ERROR: 'ERROR'>¶

CANCELLING = <JobStatusEnum.CANCELLING: 'CANCELLING'>¶

RETRYING = <JobStatusEnum.RETRYING: 'RETRYING'>¶

TERMINATED = <JobStatusEnum.TERMINATED: 'TERMINATED'>¶

DEPLETED = <JobStatusEnum.DEPLETED: 'DEPLETED'>¶

enum qnexus.jobs.JobType( value, )[source]¶

Enum for a job’s type.

Member Type:: str

Valid values are as follows:

EXECUTE = <JobType.EXECUTE: 'execute'>¶

COMPILE = <JobType.COMPILE: 'compile'>¶