toil.lib.history_submission

Contains logic for generating Toil usage history reports to send back to Toil HQ (via Dockstore), and for working out if the user wants to send them.

Attributes

logger
KeyType
Decision
DIALOG_TITLE
DIALOG_TEXT
DIALOG_OPTIONS
DIALOG_TIMEOUT

Classes

Submission

Class holding a package of information to submit to Dockstore, and the

Functions

workflow_execution_id(workflow_attempt)	Get the execution ID for a workflow attempt.
workflow_task_set_execution_id(workflow_attempt)	Get the execution ID for a workflow attempt's collection of tasks.
job_execution_id(job_attempt)	Get the execution ID for a job attempt.
get_parsed_trs_spec(workflow_attempt)	Get the TRS ID and version of the workflow, or raise an error.
create_history_submission([batch_size, desired_tasks])	Make a package of data about recent workflow runs to send in.
create_current_submission(workflow_id, attempt_number)	Make a package of data about the current workflow attempt to send in.
dialog_tkinter(title, text, options, timeout)	Display a dialog with tkinter.
display_dialog_tkinter(title, text, options, timeout, ...)	Display a dialog with tkinter in the current process.
dialog_tui(title, text, options, timeout)	Display a dialog in the terminal.
ask_user_about_publishing_metrics()	Ask the user to set standing workflow submission consent.

Module Contents

toil.lib.history_submission.logger

toil.lib.history_submission.workflow_execution_id(workflow_attempt)

Get the execution ID for a workflow attempt.

Result will follow Dockstore’s rules.

Deterministic.

Parameters:

workflow_attempt (toil.lib.history.WorkflowAttemptSummary)

Return type:

str

toil.lib.history_submission.workflow_task_set_execution_id(workflow_attempt)

Get the execution ID for a workflow attempt’s collection of tasks.

Result will follow Dockstore’s rules.

Deterministic.

Parameters:

workflow_attempt (toil.lib.history.WorkflowAttemptSummary)

Return type:

str

toil.lib.history_submission.job_execution_id(job_attempt)

Get the execution ID for a job attempt.

Result will follow Dockstore’s rules.

Deterministic.

Parameters:

job_attempt (toil.lib.history.JobAttemptSummary)

Return type:

str

toil.lib.history_submission.get_parsed_trs_spec(workflow_attempt)

Get the TRS ID and version of the workflow, or raise an error.

Returns:

The TRS ID and the TRS version of the wrokflow run.

Raises:

ValueError if the workflow does not have a TRS spec or if the spec does not contain a version.

Parameters:

workflow_attempt (toil.lib.history.WorkflowAttemptSummary)

Return type:

tuple[str, str]

class toil.lib.history_submission.Submission

Class holding a package of information to submit to Dockstore, and the information needed to mark the workflows/tasks as submitted if it is accepted.

Acceptance is at the TRS id/version combination level within the Submission, since we need one request per TRS ID/version combination.

data: dict[tuple[str, str], tuple[list[tuple[toil.lib.dockstore.RunExecution, str, int]], list[tuple[toil.lib.dockstore.TaskExecutions, list[str]]]]]

add_workflow_attempt(workflow_attempt)

Add a workflow attempt to the submission.

May raise an exception if the workflow attempt is not well-formed.

Parameters:

workflow_attempt (toil.lib.history.WorkflowAttemptSummary)

Return type:

None

add_job_attempts(workflow_attempt, job_attempts)

Add the job attempts for a workflow attempt to the submission.

Parameters:

• workflow_attempt (toil.lib.history.WorkflowAttemptSummary)

• job_attempts (list[toil.lib.history.JobAttemptSummary])

Return type:

None

empty()

Return True if there is nothing to actually submit.

Return type:

bool

report()

Compose a multi-line human-readable string report about what will be submitted.

Return type:

str

submit()

Send in workflow and task information to Dockstore.

Assumes the user has approved this already.

If submission succeeds for a TRS id/version combination, records this in the history database.

Handles errors internally. Will not raise if the submission doesn’t go through.

Returns:

False if there was any error, True if submission was accepted and recorded locally.

Return type:

bool

toil.lib.history_submission.create_history_submission(batch_size=None, desired_tasks=None)

Make a package of data about recent workflow runs to send in.

Returns a Submission object that remembers how to update the history database to record when it is successfully submitted.

Parameters:

• batch_size (Optional[int]) – Number of workflows to try and submit in one request.

• desired_tasks (Optional[int]) – Number of tasks to try and put into a task submission batch. Use 0 to not submit any task information.

Return type:

Submission

toil.lib.history_submission.create_current_submission(workflow_id, attempt_number)

Make a package of data about the current workflow attempt to send in.

Useful if the user wants to submit workflow metrics just this time.

Parameters:

• workflow_id (str)

• attempt_number (int)

Return type:

Submission

toil.lib.history_submission.KeyType

toil.lib.history_submission.dialog_tkinter(title, text, options, timeout)

Display a dialog with tkinter.

Dialog will have the given title, text, and options.

Dialog will be displayed by a separate Python process to avoid a Mac dock icon sticking around as long as Toil runs.

Parameters:

• options (dict[KeyType, str]) – Dict from machine-readable option key to button text.

• title (str)

• text (str)

• timeout (float)

Returns:

the key of the selected option, or None if the user declined to select an option.

Raises:

an exception if the dialog cannot be displayed.

Return type:

Optional[KeyType]

toil.lib.history_submission.display_dialog_tkinter(title, text, options, timeout, result_queue)

Display a dialog with tkinter in the current process.

Dialog will have the given title, text, and options.

Parameters:

• options (dict[KeyType, str]) – Dict from machine-readable option key to button text.

• title (str)

• text (str)

• timeout (float)

• result_queue (multiprocessing.Queue[Union[Exception, Optional[KeyType]]])

Return type:

None

Sends back either the key of the chosen option, or an exception, via the result queue.

toil.lib.history_submission.dialog_tui(title, text, options, timeout)

Display a dialog in the terminal.

Dialog will have the given title, text, and options.

Parameters:

• options (dict[KeyType, str]) – Dict from machine-readable option key to button text.

• title (str)

• text (str)

• timeout (float)

Returns:

the key of the selected option, or None if the user declined to select an option.

Raises:

an exception if the dialog cannot be displayed.

Return type:

Optional[KeyType]

toil.lib.history_submission.Decision

toil.lib.history_submission.DIALOG_TITLE = 'Publish Workflow Metrics on Dockstore.org?'

toil.lib.history_submission.DIALOG_TEXT = ''

toil.lib.history_submission.DIALOG_OPTIONS: dict[Decision, str]

toil.lib.history_submission.DIALOG_TIMEOUT = 120

toil.lib.history_submission.ask_user_about_publishing_metrics()

Ask the user to set standing workflow submission consent.

If the user makes a persistent decision (always or never), save it to the default Toil config file.

Returns:

The user’s decision about when to publish metrics.

Return type:

Union[Literal[‘all’], Literal[‘current’], Literal[‘no’]]