client
¶
Core module for oqtopus-client.
Classes:
-
OqtopusClient–Synchronous public client; internal HTTP calls are executed asynchronously.
OqtopusClient
¶
OqtopusClient(
config: OqtopusConfig | None = None,
default_headers: Mapping[str, str] | None = None,
user_agent: str | None = None,
)
Synchronous public client; internal HTTP calls are executed asynchronously.
Parameters:
-
(config¶Optional, default:None) –Client configuration bundle. If omitted,
OqtopusConfig.from_file()is used. In normal mode, the resolved config must provide a non-emptybase_url. -
(default_headers¶Optional, default:None) –Additional headers merged into every request.
-
(user_agent¶Optional, default:None) –Custom User-Agent header value.
Methods:
-
cancel_job–Cancel a job by id.
-
create_api_token–Create an API token.
-
delete_api_token–Delete current API token.
-
delete_job–Delete a job by id.
-
get_announcement–Get one announcement by id.
-
get_announcements_list–List service announcements.
-
get_api_token–Get API token status.
-
get_api_token_status–Get API token status.
-
get_device–Get one device by id.
-
get_job–Fetch one job by id and convert to typed SDK result.
-
get_job_result–Alias of :meth:
get_job. -
get_job_status–Get current status for one job.
-
get_sselog–Get encoded SSE log archive for one job.
-
is_finished–Return whether the job is in terminal status.
-
list_devices–List available devices.
-
list_jobs–List jobs with optional filters.
-
refresh–Alias of :meth:
get_job_result. -
result–Alias of :meth:
get_job_result. -
run_estimation–Run an estimation job and return estimation-typed SDK result.
-
run_job–Submit one job spec, wait until completion, and return typed result.
-
run_jobs_batch–Submit multiple jobs, then wait for all of them.
-
run_multi_manual–Run a multi-manual job and return multi-manual-typed SDK result.
-
run_sampling–Run a sampling job and return sampling-typed SDK result.
-
run_sse–Run an SSE job and return SSE-typed SDK result.
-
run_sse_file–Build and run an SSE job directly from a script file and return SSE result.
-
status–Get current job status enum for one job.
-
submit_job–Submit one job and return submission response.
-
submit_jobs–Submit multiple jobs in parallel.
-
submit_jobs_async–Submit multiple jobs concurrently in an async context.
-
wait–Alias of :meth:
wait_for_job. -
wait_for_job–Poll one job until terminal status/timeout and return typed result.
-
wait_for_jobs–Wait multiple jobs in parallel.
-
wait_for_jobs_async–Wait multiple jobs concurrently in an async context.
cancel_job
¶
cancel_job(job_id: str) -> SuccessSuccessResponse
Cancel a job by id.
Parameters:
-
(job_id¶Required) –Target job ID to cancel.
Returns:
-
SuccessSuccessResponse–Success response from the API.
create_api_token
¶
create_api_token() -> ApiTokenApiToken
Create an API token.
Returns:
-
ApiTokenApiToken–The created API token payload.
delete_job
¶
delete_job(job_id: str) -> SuccessSuccessResponse
Delete a job by id.
Parameters:
-
(job_id¶Required) –Target job ID to delete.
Returns:
-
SuccessSuccessResponse–Success response from the API.
get_announcement
¶
get_announcement(
announcement_id: int,
) -> AnnouncementsGetAnnouncementResponse
Get one announcement by id.
Parameters:
-
(announcement_id¶Required) –Target announcement ID.
Returns:
-
AnnouncementsGetAnnouncementResponse–The requested announcement payload.
get_announcements_list
¶
get_announcements_list() -> (
AnnouncementsGetAnnouncementsListResponse
)
List service announcements.
Returns:
-
AnnouncementsGetAnnouncementsListResponse–Announcements list returned by the API.
get_api_token
¶
get_api_token() -> ApiTokenApiTokenStatus
Get API token status.
Returns:
-
ApiTokenApiTokenStatus–The current API token status payload.
get_api_token_status
¶
get_api_token_status() -> ApiTokenApiTokenStatus
Get API token status.
Returns:
-
ApiTokenApiTokenStatus–The current API token status payload.
get_device
¶
get_device(device_id: str) -> OqtopusDevice
Get one device by id.
Parameters:
-
(device_id¶Required) –Target device ID to fetch.
Returns:
-
OqtopusDevice–The requested device wrapped as an SDK device object.
get_job
¶
get_job(job_id: str) -> OqtopusJobResult
Fetch one job by id and convert to typed SDK result.
Parameters:
-
(job_id¶Required) –Target job ID to fetch.
Returns:
-
OqtopusJobResult–The fetched job as an SDK result wrapper.
get_job_result
¶
get_job_result(job_id: str) -> OqtopusJobResult
Alias of :meth:get_job.
Parameters:
-
(job_id¶Required) –Target job ID to fetch.
Returns:
-
OqtopusJobResult–The fetched job as an SDK result wrapper.
get_job_status
¶
get_job_status(job_id: str) -> JobsGetJobStatusResponse
Get current status for one job.
Parameters:
-
(job_id¶Required) –Target job ID to get status for.
Returns:
-
JobsGetJobStatusResponse–Raw job status response from the API.
get_sselog
¶
get_sselog(job_id: str) -> JobsGetSselogResponse
Get encoded SSE log archive for one job.
Parameters:
-
(job_id¶Required) –Target SSE job ID.
Returns:
-
JobsGetSselogResponse–Encoded SSE log archive response from the API.
is_finished
¶
is_finished(
job_id: str,
*,
terminal_statuses: set[JobsJobStatus] | None = None,
) -> bool
list_devices
¶
list_devices() -> list[OqtopusDevice]
List available devices.
Returns:
-
list[OqtopusDevice]–Available devices wrapped as SDK device objects.
list_jobs
¶
list_jobs(
*,
fields: str | None = None,
start_time: datetime | None = None,
end_time: datetime | None = None,
status: JobsJobStatus | None = None,
q: str | None = None,
page: int | None = None,
size: int | None = None,
order: str | None = None,
) -> list[JobsJob]
List jobs with optional filters.
Returns:
-
list[JobsJob]–Jobs returned by the API.
refresh
¶
refresh(job_id: str) -> OqtopusJobResult
Alias of :meth:get_job_result.
Parameters:
-
(job_id¶Required) –Target job ID to fetch.
Returns:
-
OqtopusJobResult–The fetched job as an SDK result wrapper.
result
¶
result(job_id: str) -> OqtopusJobResult
Alias of :meth:get_job_result.
Parameters:
-
(job_id¶Required) –Target job ID to fetch.
Returns:
-
OqtopusJobResult–The fetched job as an SDK result wrapper.
run_estimation
¶
run_estimation(
job: OqtopusJobSpec,
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
terminal_statuses: set[JobsJobStatus] | None = None,
failure_statuses: set[JobsJobStatus] | None = None,
on_status: Callable[[JobsGetJobStatusResponse], None]
| None = None,
) -> OqtopusEstimationJobResult
Run an estimation job and return estimation-typed SDK result.
Parameters:
-
(job¶Required) –OqtopusJobSpecwithjob_type='estimation'. -
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(terminal_statuses¶Optional, default:None) –Statuses treated as terminal.
-
(failure_statuses¶Optional, default:None) –Statuses treated as failures.
-
(on_status¶Optional, default:None) –Callback invoked on each polled status.
Returns:
-
OqtopusEstimationJobResult–The finished job as an estimation result wrapper.
run_job
¶
run_job(
job: OqtopusJobSpec,
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
terminal_statuses: set[JobsJobStatus] | None = None,
failure_statuses: set[JobsJobStatus] | None = None,
on_status: Callable[[JobsGetJobStatusResponse], None]
| None = None,
) -> OqtopusJobResult
Submit one job spec, wait until completion, and return typed result.
Parameters:
-
(job¶Required) –OqtopusJobSpec. -
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(terminal_statuses¶Optional, default:None) –Statuses treated as terminal.
-
(failure_statuses¶Optional, default:None) –Statuses treated as failures.
-
(on_status¶Optional, default:None) –Callback invoked on each polled status.
Returns:
-
OqtopusJobResult–The finished job as an SDK result wrapper.
run_jobs_batch
¶
run_jobs_batch(
jobs: list[OqtopusJobSpec],
*,
submit_workers: int = 4,
wait_workers: int = 4,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
) -> list[OqtopusJobResult]
Submit multiple jobs, then wait for all of them.
Parameters:
-
(jobs¶Required) –List of
OqtopusJobSpec. -
(submit_workers¶Optional, default:4) –Submission concurrency. Default is
4. -
(wait_workers¶Optional, default:4) –Waiting concurrency. Default is
4. -
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
Returns:
-
list[OqtopusJobResult]–Finished jobs as SDK result wrappers.
Raises:
-
TypeError–If any item in
jobsis not anOqtopusJobSpec. -
ValueError–If
submit_workersis less than1.
run_multi_manual
¶
run_multi_manual(
job: OqtopusJobSpec,
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
terminal_statuses: set[JobsJobStatus] | None = None,
failure_statuses: set[JobsJobStatus] | None = None,
on_status: Callable[[JobsGetJobStatusResponse], None]
| None = None,
) -> OqtopusMultiManualJobResult
Run a multi-manual job and return multi-manual-typed SDK result.
Parameters:
-
(job¶Required) –OqtopusJobSpecwithjob_type='multi_manual'. -
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(terminal_statuses¶Optional, default:None) –Statuses treated as terminal.
-
(failure_statuses¶Optional, default:None) –Statuses treated as failures.
-
(on_status¶Optional, default:None) –Callback invoked on each polled status.
Returns:
-
OqtopusMultiManualJobResult–The finished job as a multi-manual result wrapper.
run_sampling
¶
run_sampling(
job: OqtopusJobSpec,
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
terminal_statuses: set[JobsJobStatus] | None = None,
failure_statuses: set[JobsJobStatus] | None = None,
on_status: Callable[[JobsGetJobStatusResponse], None]
| None = None,
) -> OqtopusSamplingJobResult
Run a sampling job and return sampling-typed SDK result.
Parameters:
-
(job¶Required) –OqtopusJobSpecwithjob_type='sampling'. -
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(terminal_statuses¶Optional, default:None) –Statuses treated as terminal.
-
(failure_statuses¶Optional, default:None) –Statuses treated as failures.
-
(on_status¶Optional, default:None) –Callback invoked on each polled status.
Returns:
-
OqtopusSamplingJobResult–The finished job as a sampling result wrapper.
run_sse
¶
run_sse(
job: OqtopusJobSpec,
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
terminal_statuses: set[JobsJobStatus] | None = None,
failure_statuses: set[JobsJobStatus] | None = None,
on_status: Callable[[JobsGetJobStatusResponse], None]
| None = None,
) -> OqtopusSseJobResult
Run an SSE job and return SSE-typed SDK result.
Parameters:
-
(job¶Required) –OqtopusJobSpecwithjob_type='sse'. -
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(terminal_statuses¶Optional, default:None) –Statuses treated as terminal.
-
(failure_statuses¶Optional, default:None) –Statuses treated as failures.
-
(on_status¶Optional, default:None) –Callback invoked on each polled status.
Returns:
-
OqtopusSseJobResult–The finished job as an SSE result wrapper.
run_sse_file
¶
run_sse_file(
*,
file_path: str | Path,
device_id: str,
name: str | None = None,
description: str | None = None,
transpiler_info: dict[str, object] | None = None,
simulator_info: dict[str, object] | None = None,
mitigation_info: dict[str, object] | None = None,
shots: int = 1,
max_file_size: int = 10 * 1024 * 1024,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
terminal_statuses: set[JobsJobStatus] | None = None,
failure_statuses: set[JobsJobStatus] | None = None,
on_status: Callable[[JobsGetJobStatusResponse], None]
| None = None,
) -> OqtopusSseJobResult
Build and run an SSE job directly from a script file and return SSE result.
Parameters:
-
(file_path¶Required) –Path to the Python script.
-
(device_id¶Required) –Target device ID.
-
(name¶Optional, default:None) –Job name.
-
(description¶Optional, default:None) –Job description.
-
(transpiler_info¶Optional, default:None) –Transpiler settings.
-
(simulator_info¶Optional, default:None) –Simulator settings.
-
(mitigation_info¶Optional, default:None) –Error mitigation settings.
-
(shots¶Optional, default:1) –Number of shots.
-
(max_file_size¶Optional, default:10 * 1024 * 1024) –Max script size in bytes.
-
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(terminal_statuses¶Optional, default:None) –Statuses treated as terminal.
-
(failure_statuses¶Optional, default:None) –Statuses treated as failures.
-
(on_status¶Optional, default:None) –Callback invoked on each polled status.
Returns:
-
OqtopusSseJobResult–The finished job as an SSE result wrapper.
status
¶
status(job_id: str) -> JobsJobStatus
Get current job status enum for one job.
Parameters:
-
(job_id¶Required) –Target job ID to get status for.
Returns:
-
JobsJobStatus–The current job status.
submit_job
¶
submit_job(body: OqtopusJobSpec) -> JobsRegisterJobResponse
Submit one job and return submission response.
Parameters:
-
(body¶Required) –OqtopusJobSpec.
Returns:
-
JobsRegisterJobResponse–Submission response for the created job.
Raises:
-
TypeError–If
bodyis not anOqtopusJobSpec.
submit_jobs
¶
submit_jobs(
jobs: Sequence[OqtopusJobSpec], *, max_workers: int = 4
) -> list[JobsRegisterJobResponse]
Submit multiple jobs in parallel.
Parameters:
-
(jobs¶Required) –List of
OqtopusJobSpec. -
(max_workers¶Optional, default:4) –Submission concurrency. Default is
4.
Returns:
-
list[JobsRegisterJobResponse]–Submission responses for all jobs.
Raises:
-
TypeError–If any item in
jobsis not anOqtopusJobSpec. -
ValueError–If
max_workersis less than1.
submit_jobs_async
async
¶
submit_jobs_async(
jobs: Sequence[OqtopusJobSpec], *, max_workers: int = 4
) -> list[JobsRegisterJobResponse]
Submit multiple jobs concurrently in an async context.
Parameters:
-
(jobs¶Required) –List of
OqtopusJobSpec. -
(max_workers¶Optional, default:4) –Submission concurrency. Default is
4.
Returns:
-
list[JobsRegisterJobResponse]–Submission responses for all jobs.
Raises:
-
TypeError–If any item in
jobsis not anOqtopusJobSpec. -
ValueError–If
max_workersis less than1.
wait
¶
wait(
job_id: str,
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
terminal_statuses: set[JobsJobStatus] | None = None,
failure_statuses: set[JobsJobStatus] | None = None,
on_status: Callable[[JobsGetJobStatusResponse], None]
| None = None,
) -> OqtopusJobResult
Alias of :meth:wait_for_job.
Parameters:
-
(job_id¶Required) –Target job ID to wait for.
-
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(terminal_statuses¶Optional, default:None) –Statuses treated as terminal.
-
(failure_statuses¶Optional, default:None) –Statuses treated as failures.
-
(on_status¶Optional, default:None) –Callback invoked on each polled status.
Returns:
-
OqtopusJobResult–The finished job as an SDK result wrapper.
wait_for_job
¶
wait_for_job(
job_id: str,
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
terminal_statuses: set[JobsJobStatus] | None = None,
failure_statuses: set[JobsJobStatus] | None = None,
on_status: Callable[[JobsGetJobStatusResponse], None]
| None = None,
) -> OqtopusJobResult
Poll one job until terminal status/timeout and return typed result.
Parameters:
-
(job_id¶Required) –Target job ID to wait for.
-
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(terminal_statuses¶Optional, default:None) –Statuses treated as terminal.
-
(failure_statuses¶Optional, default:None) –Statuses treated as failures.
-
(on_status¶Optional, default:None) –Callback invoked on each polled status.
Returns:
-
OqtopusJobResult–The finished job as an SDK result wrapper.
wait_for_jobs
¶
wait_for_jobs(
job_ids: list[str],
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
max_workers: int = 4,
) -> list[OqtopusJobResult]
Wait multiple jobs in parallel.
Parameters:
-
(job_ids¶Required) –List of job IDs to wait for.
-
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(max_workers¶Optional, default:4) –Waiting concurrency. Default is
4.
Returns:
-
list[OqtopusJobResult]–Finished jobs as SDK result wrappers.
Raises:
-
ValueError–If
max_workersis less than1.
wait_for_jobs_async
async
¶
wait_for_jobs_async(
job_ids: list[str],
*,
interval: float = 1.0,
interval_backoff: float = 1.0,
max_interval: float | None = None,
timeout: float | None = 300.0,
max_workers: int = 4,
) -> list[OqtopusJobResult]
Wait multiple jobs concurrently in an async context.
Parameters:
-
(job_ids¶Required) –List of job IDs to wait for.
-
(interval¶Optional, default:1.0) –Polling interval in seconds.
-
(interval_backoff¶Optional, default:1.0) –Backoff multiplier for polling interval.
-
(max_interval¶Optional, default:None) –Upper bound of polling interval in seconds.
-
(timeout¶Optional, default:300.0) –Timeout in seconds.
-
(max_workers¶Optional, default:4) –Waiting concurrency. Default is
4.
Returns:
-
list[OqtopusJobResult]–Finished jobs as SDK result wrappers.
Raises:
-
ValueError–If
max_workersis less than1.