tomato.ketchup: CLI and API for 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

Warning

This module interacts with the job sqlite database directly. This means that users submitting jobs to tomato must have write access to the job database file.

tomato.ketchup.submit(*, payload: str | Path, jobname: str | None, daemon: Daemon, **_: 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
  connected_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(*, jobids: list[int], daemon: 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
  connected_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(*, jobids: list[int], daemon: 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
  connected_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], daemon: 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

>>> # With yaml output:
>>> ketchup snapshot 1 -y
data: null
msg: snapshot for job [1] created successfully
success: true

tomato.ketchup.search(*, jobname: str, daemon: 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