tomato.ketchup package

tomato.ketchup: command line interface to the tomato job queue

Code author: Peter Kraus

Module of functions to manage the job queue of tomato. Includes job management functions:

submit() to submit a job to queue
status() to query the status of tomato’s queue, or a job
cancel() to cancel a queued or kill a running job
snapshot() to create an up-to-date FAIR data archive of a running job
search() to find a jobid of a job from jobname

tomato.ketchup.submit(*, port: int, timeout: int, context: Context, payload: str, jobname: str, **_: dict) → Reply

Job submission function.

Attempts to open the yaml/json file specified in the payload argument, and submit it to tomato’s queue.

Reply contains information about the submitted job.

Examples

>>> # Submit a job:
>>> ketchup submit counter_15_0.1.yml
Success: job submitted successfully with jobid 1

>>> # Submit a job with a job name:
>>> ketchup submit counter_15_0.1.yml -j jobname_is_this
Success: job submitted successfully with jobid 1 and jobname 'jobname_is_this'

>>> # Submit a job with yaml output:
>>> ketchup submit counter_15_0.1.yml -y
data:
    completed_at: null
    executed_at: null
    id: 1
    [...]
    status: q
    submitted_at: '2024-11-17 19:39:16.972593+00:00'
msg: job submitted successfully with jobid 1
success: true

tomato.ketchup.status(*, port: int, timeout: int, context: Context, verbosity: int, jobids: list[int], status: Daemon, **_: dict) → Reply

Job status query function.

Reply contains information about all matched jobs.

Note

Calling ketchup status with a single jobid will return a yaml list, even though status of only one element was queried.

Examples

>>> # Get status of a given job
>>> ketchup status 1
Success: found 1 job with status 'qw': [1]

>>> # Get status of multiple jobs
>>> ketchup status 1 2
Success: found 2 job with status 'qw': [1]
         found 1 job with status 'c' : [2]

>>> # Get status of non-existent job
>>> ketchup status 3
Failure: found no jobs with jobids [3]

>>> # Get a status of a job with yaml output
>>> ketchup status 1 -y
data:
  - completed_at: null
    executed_at: null
    id: 1
    [...]
    status: qw
    submitted_at: '2024-11-17 17:53:46.133355+00:00'
msg: found 1 job with status ['qw']
success: true

tomato.ketchup.cancel(*, port: int, timeout: int, context: Context, jobids: list[int], status: Daemon, **_: dict) → Reply

Job cancellation function.

Note

The cancel() only sets the status of the running job to rd; the actual job cancellation is performed in the tomato.daemon.job module.

Examples

>>> # Cancel a job:
>>> ketchup cancel 1
Success: job [1] cancelled successfully

>>> # Cancel a job with yaml output:
>>> ketchup cancel 2 -y
data:
  - completed_at: null
    executed_at: null
    id: 2
    [...]
    status: cd
    submitted_at: '2024-03-03 15:23:50.702504+00:00'
msg: job [2] cancelled successfully
success: true

tomato.ketchup.snapshot(*, jobids: list[int], status: Daemon, **_: dict) → Reply

Create a snapshot of job data.

Requests an up-to-date snapshot of the data of the job identified by jobid. Checks whether the job is running, raises a warning if job has been finished.

Examples

>>> # Create a snapshot in current working directory:
>>> ketchup snapshot 3
Success: snapshot for job [3] created successfully

tomato.ketchup.search(*, jobname: str, status: Daemon, **_: dict) → Reply

Search the queue for a job that matches a given jobname.

Searches the queue for a job that matches the jobname, returns the job status and jobid.

Examples

>>> # Search for a valid jobname
>>> ketchup search counter
Success: job matching 'counter' found: [1]

>>> # Search for an invalid jobname
>>> ketchup search nothing
Failure: no job matching 'nothing' found