aistore.sdk.job | NVIDIA AIStore

Module Contents

Classes

Name	Description
`Job`	A class containing job-related functions.
`_IdleStreak`	Idle-wait done-condition mirroring Go’s `xact.snapsIdle`: the job must

Data

NUM_CONSECUTIVE_IDLE

logger

API

class aistore.sdk.job.Job(
    client: aistore.sdk.request_client.RequestClient,
    job_id: str = '',
    job_kind: str = ''
)

A class containing job-related functions.

Parameters:

client

RequestClient

Client for interfacing with AIS cluster

job_id

strDefaults to ''

ID of a specific job, empty for all jobs

job_kind

strDefaults to ''

Specific kind of job, empty for all kinds

job_id

Return job id

job_kind

Return job kind

aistore.sdk.job.Job._resolve_kind() -> str

Look up this job’s kind from the cluster by id and cache it, so wait() can dispatch correctly when only a job id was provided.

Raises:

JobInfoNotFound: if no snapshot for job_id is found

aistore.sdk.job.Job._wait_for_condition(
    condition_fn,
    timeout: int,
    verbose: bool,
    state: str
) -> aistore.sdk.wait_result.WaitResult

aistore.sdk.job.Job._wait_terminal(
    timeout: int,
    verbose: bool
) -> aistore.sdk.wait_result.WaitResult

Poll status() until the job reaches a terminal state.

aistore.sdk.job.Job.abort() -> None

Abort (stop) this job.

After aborting, wait() (or wait_for_idle) will return a WaitResult with success=False and the abort error rather than blocking until timeout.

Raises:

ValueError: If neither job_id nor job_kind is set
requests.RequestException: “There was an ambiguous exception that occurred while handling…”
requests.ConnectionError: Connection error
requests.ConnectionTimeout: Timed out connecting to AIStore
requests.ReadTimeout: Timed out waiting response from AIStore

aistore.sdk.job.Job.get_details() -> aistore.sdk.types.AggregatedJobSnap

Retrieve detailed job snapshot information across all targets.

Returns: AggregatedJobSnap

A snapshot containing detailed metrics for the job.

aistore.sdk.job.Job.get_total_time() -> typing.Optional[datetime.timedelta]

Calculates the total job duration as the difference between the earliest start time and the latest end time among all job snapshots. If any snapshot is missing an end_time, returns None to indicate the job is incomplete.

Returns: Optional[timedelta]

Optional[timedelta]: The total duration of the job, or None if incomplete.

aistore.sdk.job.Job.get_within_timeframe(
    start_time: datetime.datetime,
    end_time: typing.Optional[datetime.datetime] = None
) -> typing.List[aistore.sdk.types.JobSnap]

Retrieves jobs that started after a specified start_time and optionally ended before a specified end_time.

Parameters:

start_time

datetime

The start of the timeframe for monitoring jobs.

end_time

datetimeDefaults to None

The end of the timeframe for monitoring jobs.

Returns: List[JobSnap]

List[JobSnapshot]: A list of jobs that meet the specified timeframe criteria.

Raises:

JobInfoNotFound: Raised when no relevant job info is found.

aistore.sdk.job.Job.start(
    daemon_id: str = '',
    force: bool = False,
    buckets: typing.Optional[typing.List[aistore.sdk.bucket.Bucket]] = None
) -> str

Start a job and return its ID.

Parameters:

daemon_id

strDefaults to ''

For running a job that must run on a specific target node (e.g. resilvering).

force

boolDefaults to False

Override existing restrictions for a bucket (e.g., run LRU eviction even if the bucket has LRU disabled).

buckets

List[Bucket]Defaults to None

List of one or more buckets; applicable only for jobs that have bucket scope (for details on job types, see Table in xact/api.go).

Returns: str

The running job ID.

Raises:

requests.RequestException: “There was an ambiguous exception that occurred while handling…”
requests.ConnectionError: Connection error
requests.ConnectionTimeout: Timed out connecting to AIStore
requests.ReadTimeout: Timed out waiting response from AIStore

aistore.sdk.job.Job.status() -> aistore.sdk.types.JobStatus

Return status of a job

Returns: JobStatus

The job status including id, finish time, and error info

Raises:

ValueError: If the job does not have an assigned ID
requests.RequestException: “There was an ambiguous exception that occurred while handling…”
requests.ConnectionError: Connection error
requests.ConnectionTimeout: Timed out connecting to AIStore
requests.ReadTimeout: Timed out waiting response from AIStore

aistore.sdk.job.Job.wait(
    timeout: int = DEFAULT_JOB_WAIT_TIMEOUT,
    verbose: bool = True
) -> aistore.sdk.wait_result.WaitResult

Wait for a job to reach the appropriate “done” state for its kind.

Mirrors the Go-side api/xaction.go: WaitForXaction(bp, args) descriptor-aware dispatch:

if self.job_kind is an idle kind (e.g. download, get-batch, copy-listrange, etl-listrange, archive, list, put-copies, ec-get/ec-put/ec-resp), wait for the job to reach an idle state across all targets (see wait_for_idle).
otherwise (including unknown or empty kind), wait for the job to reach a terminal state (its end_time becomes set).

If job_kind is empty but job_id is set, the kind is first resolved from the cluster so the job dispatches correctly (raising JobInfoNotFound if the id does not exist).

Idle is confirmed over NUM_CONSECUTIVE_IDLE consecutive polls; an abort on any target returns immediately with success=False.

For finer control (single-node fan-out, explicit idle/terminal), call wait_for_idle or wait_single_node directly.

Parameters:

timeout

intDefaults to DEFAULT_JOB_WAIT_TIMEOUT

The maximum time to wait for the job, in seconds. Default timeout is 5 minutes.

verbose

boolDefaults to True

Whether to log wait status to standard output

Returns: WaitResult

Outcome of the wait operation

Raises:

requests.RequestException: “There was an ambiguous exception that occurred while handling…”
requests.ConnectionError: Connection error
requests.ConnectionTimeout: Timed out connecting to AIStore
requests.ReadTimeout: Timed out waiting response from AIStore
errors.Timeout: Timeout while waiting for the job to finish
errors.JobInfoNotFound: If job_kind is empty and job_id is not found

aistore.sdk.job.Job.wait_for_idle(
    timeout: int = DEFAULT_JOB_WAIT_TIMEOUT,
    verbose: bool = True
) -> aistore.sdk.wait_result.WaitResult

Wait for a job to reach an idle state

Parameters:

timeout

intDefaults to DEFAULT_JOB_WAIT_TIMEOUT

The maximum time to wait for the job, in seconds. Default timeout is 5 minutes.

verbose

boolDefaults to True

Whether to log wait status to standard output

Returns: WaitResult

Outcome of the wait operation

Raises:

requests.RequestException: “There was an ambiguous exception that occurred while handling…”
requests.ConnectionError: Connection error
requests.ConnectionTimeout: Timed out connecting to AIStore
requests.ReadTimeout: Timed out waiting response from AIStore
errors.Timeout: Timeout while waiting for the job to finish

aistore.sdk.job.Job.wait_single_node(
    timeout: int = DEFAULT_JOB_WAIT_TIMEOUT,
    verbose: bool = True
) -> aistore.sdk.wait_result.WaitResult

Wait for a job running on a single node

Parameters:

timeout

intDefaults to DEFAULT_JOB_WAIT_TIMEOUT

The maximum time to wait for the job, in seconds. Default timeout is 5 minutes.

verbose

boolDefaults to True

Whether to log wait status to standard output

Returns: WaitResult

Outcome of the wait operation

Raises:

requests.RequestException: “There was an ambiguous exception that occurred while handling…”
requests.ConnectionError: Connection error
requests.ConnectionTimeout: Timed out connecting to AIStore
requests.ReadTimeout: Timed out waiting response from AIStore
errors.Timeout: Timeout while waiting for the job to finish

class aistore.sdk.job._IdleStreak()

Idle-wait done-condition mirroring Go’s xact.snapsIdle: the job must report idle on NUM_CONSECUTIVE_IDLE consecutive polls before completing; an abort on any target completes immediately.

_count

= 0

aistore.sdk.job._IdleStreak.__call__(
    details: aistore.sdk.types.AggregatedJobSnap
) -> bool

aistore.sdk.job.NUM_CONSECUTIVE_IDLE = 2

aistore.sdk.job.logger = get_logger(__name__)