QCloudJob

QCloudJob tracks a submitted cloud task.

Signature

QCloudJob(job_id: str)

Most code receives a QCloudJob from QCloudBackend.run() or run_instruction(). The constructor can also be called directly with a job ID to reattach to a previously submitted job and query or fetch its result.

Methods

job_id

job_id() -> str

Return the cloud job id.

status

status() -> JobStatus

Return the latest lifecycle state.

query

query(keys: str | list[str] | None = None, key: str | None = None) -> QCloudResult

Fetch the latest job metadata without waiting for final completion.

result

result(keys: str | list[str] | None = None, key: str | None = None) -> QCloudResult

result() keeps polling only while the status is WAITING / COMPUTING / QUEUING; FINISHED / FAILED return immediately. A server-reported task failure returns a QCloudResult whose job_status() is JobStatus.FAILED and whose error_message() gives the reason; it no longer raises RuntimeError (network, protocol, or HTTP errors may still be raised).

cancel

cancel() -> bool

Cancel the current cloud job. Returns True if the cloud service accepted the cancellation request, False if the service responded that the task cannot be cancelled.

cancel_task

cancel_task(task_id: str) -> bool

Cancel a cloud task by task ID (static method, called on the QCloudJob class). QCloudService must be initialized first so the SDK has the cloud URL and authorization information.

Parameters

Parameter	Type	Description
task_id	str	The cloud task ID to cancel.

Returns

True if the cloud service accepted the cancellation request, False if the service responded that the task cannot be cancelled.

Example

from pyqpanda3.core import H, QProg, measure
from pyqpanda3.qcloud import JobStatus, QCloudService

service = QCloudService("your_api_key")
backend = service.backend("full_amplitude")

prog = QProg()
prog << H(0) << measure(0, 0)

job = backend.run(prog, shots=1000)
print(job.job_id())
print(job.status())

result = job.result(keys=["mappingQprog", "mappingQubit", "probCount"])
print(result.job_status())
print(result.get_probs())
print(result.mapping_qubit() if "mappingQubit" in result else "")
print(result.timing_info())

Example output shape:

JOB_ID
JobStatus.WAITING
JobStatus.FINISHED
{'0x0': 0.5, '0x1': 0.5}
{"0": 1}
{'totalTime': 1234, ...}

Failure handling:

if result.job_status() == JobStatus.FAILED:
    print("failed:", result.error_message())
else:
    print(result.get_probs())

Cancelling tasks requires cloud credentials and a real task, so it cannot be executed locally:

from pyqpanda3.qcloud import QCloudJob, QCloudService

# Requires cloud credentials and a real task; cannot run locally
service = QCloudService("your_api_key")
job = QCloudJob("your_job_id")

print(job.cancel())                          # cancel the current job
print(QCloudJob.cancel_task("your_task_id"))  # cancel by task ID (static)

Notes

• query() returns current task metadata; result() waits for completion and returns final results.

NOTE

Additional raw fields

The pyqpanda3 0.4.0 source bindings support keys= or key=; the two cannot be passed together. Common fields include mappingQprog, mappingQubit, probCount, convertQProg, srcQubits, targetCbits, and measureQubits.

• keys accepts a string or a list of strings; key is the single-field convenience form. Do not pass both. Use QCloudResult.origin_data() when you need the complete raw server JSON.

See Also

• QCloudResult
• QCloudService and QCloudBackend