COMPS.Data.WorkItem module#

class COMPS.Data.WorkItem.WorkItem(name, worker, environment_name, description=None, asset_collection_id=None, priority=None)[source]#

Bases: TaggableEntity, CommissionableEntity, RelatableEntity, SerializableEntity

Represents a single work-item.

Contains various basic properties accessible by getters (and, in some cases, +setters):

  • id

  • +name

  • +description

  • owner

  • date_created

  • last_modified

  • state

  • error_message

  • worker

  • environment_name

  • host_name

  • worker_instance_id

  • priority

  • working_directory

  • working_directory_size

  • asset_collection_id

Also contains “child objects” (which must be specifically requested for retrieval using the QueryCriteria.select_children() method of QueryCriteria):

  • tags

  • files

  • plugins

property id#
property name#
property worker#
property environment_name#
property description#
property owner#
property date_created#
property last_modified#
property state#
property error_message#
property host_name#
property worker_instance_id#
property priority#
property working_directory#
property working_directory_size#
property asset_collection_id#
property tags#
property files#
property plugins#
classmethod get(id=None, query_criteria=None)[source]#

Retrieve one or more WorkItems.

Parameters:
  • id – The id (str or UUID) of the WorkItem to retrieve

  • query_criteria – A QueryCriteria object specifying basic property filters and tag-filters to apply to the set of WorkItems returned, as well as which properties and child-objects to fill for the returned WorkItems

Returns:

A WorkItem or list of WorkItems (depending on whether ‘id’ was specified) with basic properties and child-objects assigned as specified by ‘query_criteria’

refresh(query_criteria=None)[source]#

Update properties of an existing WorkItem from the server.

Parameters:

query_criteria – A QueryCriteria object specifying which properties and child-objects to refresh on the WorkItem

Get a list of WorkItems related to this WorkItem

Parameters:

relation_type – A RelationType object specifying which related WorkItems to filter to. If none is specified, all related WorkItems are returned.

Get a list of Suites related to this WorkItem

Parameters:

relation_type – A RelationType object specifying which related Suites to filter to. If none is specified, all related Suites are returned.

Get a list of Experiments related to this WorkItem

Parameters:

relation_type – A RelationType object specifying which related Experiments to filter to. If none is specified, all related Experiments are returned.

Get a list of Simulations related to this WorkItem

Parameters:

relation_type – A RelationType object specifying which related Simulations to filter to. If none is specified, all related Simulations are returned.

Get a list of AssetCollections related to this WorkItem

Parameters:

relation_type – A RelationType object specifying which related AssetCollections to filter to. If none is specified, all related AssetCollections are returned.

Add a relationship between this WorkItem and a related WorkItem

Parameters:
  • related_id – The id (str or UUID) of the related WorkItem

  • relation_type – The RelationType that describes how this WorkItem is related to the related WorkItem

Add a relationship between this WorkItem and a related Suite

Parameters:
  • related_id – The id (str or UUID) of the related Suite

  • relation_type – The RelationType that describes how this WorkItem is related to the related Suite

Add a relationship between this WorkItem and a related Experiment

Parameters:
  • related_id – The id (str or UUID) of the related Experiment

  • relation_type – The RelationType that describes how this WorkItem is related to the related Experiment

Add a relationship between this WorkItem and a related Simulation

Parameters:
  • related_id – The id (str or UUID) of the related Simulation

  • relation_type – The RelationType that describes how this WorkItem is related to the related Simulation

Add a relationship between this WorkItem and a related AssetCollection

Parameters:
  • related_id – The id (str or UUID) of the related AssetCollection

  • relation_type – The RelationType that describes how this WorkItem is related to the related AssetCollection

save(return_missing_files=False, save_semaphore=None)[source]#

Save a single WorkItem. If it’s a new WorkItem, an id is automatically assigned.

Parameters:

return_missing_files – A boolean that determines the behavior when the WorkItem being saved contains a WorkItemFile to be saved by md5 checksum (i.e. without uploading the data) that is not yet in COMPS. If true, when there are such files, return an array of UUIDs representing the md5 checksums of the missing files. If false, raise an error when there are any such files.

classmethod get_save_semaphore()[source]#
static save_all(save_batch_callback=<function WorkItem.<lambda>>, return_missing_files=False, save_semaphore=None)[source]#

Batch-save all unsaved WorkItems.

WorkItems are saved in batches of at most ‘__max_wi_batch_count’ and with a maximum request size of ‘__max_wi_batch_request_size_kb’.

Parameters:
  • save_batch_callback – Callback to call whenever a request to save a batch of WorkItems completes. Default behavior is to print a single ‘.’ to the console. If the callback supplied takes 1 argument, the number of WorkItems saved so far will be passed when it is called.

  • return_missing_files – A boolean that determines the behavior when any of the WorkItems being saved contains a WorkItemFile to be saved by md5 checksum (i.e. without uploading the data) that is not yet in COMPS. If true, when there are such files, return an array of UUIDs representing the md5 checksums of the missing files. If false, raise an error when there are any such files.

add_work_order(file_path=None, data=None)[source]#

Add the WorkOrder for a WorkItem.

The contents of the WorkOrder file to add can be specified either by providing a path to the file or by providing the actual data as a string.

Parameters:
  • file_path – The path to the work-order file to add.

  • data – The actual bytes of work-order data to add.

add_file(workitemfile, file_path=None, data=None, upload_callback=<function WorkItem.<lambda>>)[source]#

Add a WorkItemFile to a WorkItem.

The contents of the file to add can be specified either by providing a path to the file or by providing the actual data as a byte-array. Alternately, if the file/data is already in COMPS, you can skip uploading it again and just provide a WorkItemFile that contains the md5 checksum of the data.

If the file exceeds AssetManager.large_asset_upload_threshold bytes in size, the file will be uploaded immediately, separately from the saving of the main WorkItem. This allows saving of arbitrarily-large files while avoiding potential timeouts or having to start from scratch in case the upload is interrupted by network issues.

NOTE: providing both file/data and an md5 is considered invalid, as providing the md5 implies the caller knows the file/data is already in COMPS and doesn’t need to be uploaded again.

Parameters:
  • workitemfile – A WorkItemFile containing the metadata for the file to add.

  • file_path – The path to the file to add.

  • data – The actual bytes of data to add.

  • upload_callback – Callback to call whenever a large file upload completes saving of a chunk of the file. Default behavior is to print a single ‘.’ to the console. If the callback supplied takes 1 argument, the number of bytes saved so far will be passed when it is called.

retrieve_output_files(paths, as_zip=False)[source]#

Retrieve output files associated with this WorkItem.

This essentially combines the functionality of retrieve_output_file_info() and retrieve_output_filess_from_info(), and can be used if user doesn’t care about specific metadata related to the files being retrieved.

Parameters:
  • paths – Partial paths (relative to the working directory) of the output files to retrieve. If ‘as_zip’ is true, this can be None/empty or not specified, and all output files will be included in the zip returned.

  • as_zip – A boolean controlling whether the output files are returned individually or as a single zip-file (useful for attaching to an e-mail, etc).

Returns:

If ‘as_zip’ is true, returns a single byte-array of a zip-file; otherwise, returns a list of byte-arrays of the output files retrieved, in the same order as the ‘paths’ parameter.

retrieve_output_file_info(paths)[source]#

Retrieve OutputFileMetadata about output files associated with this WorkItem.

Parameters:

paths – Partial paths (relative to the working directory) of the output files to retrieve. If None/empty or not specified, will default to return all output files.

Returns:

A list of OutputFileMetadata objects for the output files to retrieve, in the same order as the ‘paths’ parameter.

retrieve_output_files_from_info(metadata, as_zip=False)[source]#

Actually retrieve the output files associated with this WorkItem.

Parameters:
  • metadata – A list of OutputFileMetadata objects representing the output files to retrieve associated with this WorkItem.

  • as_zip – A boolean controlling whether the output files are returned individually or as a single zip-file (useful for attaching to an e-mail, etc).

Returns:

If ‘as_zip’ is true, returns a single byte-array of a zip-file; otherwise, returns a list of byte-arrays of the output files retrieved, in the same order as the ‘paths’ parameter.

static static_retrieve_output_files(workitem_id, paths, as_zip=False)[source]#
class COMPS.Data.WorkItem.WorkerOrPluginKey(name, version)#

Bases: tuple

name#

Alias for field number 0

version#

Alias for field number 1

class COMPS.Data.WorkItem.WorkItemState(value)[source]#

Bases: Enum

An enumeration representing the current state of a WorkItem

Created = 0#
CommissionRequested = 5#
Commissioned = 10#
Validating = 30#
Running = 40#
Waiting = 50#
ResumeRequested = 60#
CancelRequested = 80#
Canceled = 90#
Resumed = 100#
Canceling = 120#
Succeeded = 130#
Failed = 140#
class COMPS.Data.WorkItem.RelationType(value)[source]#

Bases: Enum

An enumeration representing the type of relationship for related entities

DependsOn = 0#
Created = 1#