Scripts¶
Listed here are the definitions of the various base classes of scripts.
Derived Sample Automation Script¶
-
class
s4.clarity.scripts.
DerivedSampleAutomation
(options)¶ Bases:
s4.clarity.scripts.GenericScript
A script run from the Project Dashboard screen.
Variables: Parameters: options (map) – A map of the values of the supplied command line arguments. The default keys available are: username, password, api_uri, and derived_sample_ids.
Usage:
Implement process_derived_samples(), which must return a string to display success status to the user.
- Optionally:
- add_arguments(argparser) # To add more arguments. Don’t forget to call super.
Add to the end of your file:
- if __name__ == ‘__main__’:
- YourSubClass.main()
Example Clarity automation string. Contains an example of additional user input that would require an override of add_arguments to add the -x arg. Note that all userinput args are strings:
python <script_name>.py -u {username} -p {password} -a '{baseURI}v2' -d {derivedSampleLuids} -x {userinput:input_x}
-
classmethod
add_arguments
(argparser)[source]¶ Configures the Argument Parser to read command line input and store it in the self.options object.
This method can be overrode in sub classes to provide extra arguments specific to the script being written. When this is done it is important to call the parent class add_arguemnts methods so that all arguments are included.
Parameters: parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.
-
process_derived_samples
()[source]¶ Implement this to perform the work required. Method must return a summary success string, as it’s used to display the user-facing message on script completion.
Returns: Message to report success to the user Return type: str Raise: Exception to report failure
-
run
()[source]¶ The run method is called once the arguments are parsed and the logging is started. It will return an exit code indicating the success or failure of the process to run. Exit Codes: http://www.tldp.org/LDP/abs/html/exitcodes.html
Returns: The Exit code
Generic Script¶
-
class
s4.clarity.scripts.
GenericScript
(options)¶ GenericScript is the base abstract class for all of our script classes. The class provides common logging, argument parsing and entry point for all other script types.
The GenericScript provides the main() method as an entry point for all scripts. Because your implementing class will be the main entry point for the program it will need to call the main method.
The following code will make sure that the script is only run _if_ the file is the main python entry point:
- if __name__ == ‘__main__’:
- YourSubClass.main()
For more information on this see:
Command line arguments can be added by overriding the add_arguments method. Remember to call the parent implementation of add_arguments so that all arguments are included.
Example method adding an extra command line argument:
@classmethod def add_arguments(cls, argparser): super(YourSubClass, cls).add_arguments(argparser) argparser.add_argument( '-t', '--thisparam', type=str, help='Something helpful', required=True )
The values will be available in the self.options object.
An example of printing the value passed in as –thisparam print self.options.thisparam
This class works with the python logging system to gather log information and save it to a file. The files can be stored as html or plain text.
To use this logging system in your own files declare the logging object at the top of each file:
log = logging.getLogger(__name__)The log object can then be used to log information that the GenericScript will save.
log.info(“Low priority info to log.”) log.warning(“Warnings to log”) log.error(“Error conditions logged”)
To add functionality to a class derived from GenericScript the run() method must be overrode in the child class.
Creates a new instance of this class and saves the command line options
Parameters: options (argparse.Namespace) – The parsed command line options -
TEXT_LOG_FORMAT
= '%(asctime)s\t%(levelname)s\t%(name)s: %(message)s'¶
-
classmethod
add_arguments
(parser)[source]¶ Configures the Argument Parser to read command line input and store it in the self.options object.
This method can be overrode in sub classes to provide extra arguments specific to the script being written. When this is done it is important to call the parent class add_arguemnts methods so that all arguments are included.
Parameters: parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.
-
final_summary
= ''¶
-
classmethod
main
()[source]¶ The entry point for all scripts. This method will exit() the program upon completion.
-
open_log_output_stream
()[source]¶ override this for more complicated logging output.
Return type: io.IOBase
-
run
(*args)[source]¶ The run method is called once the arguments are parsed and the logging is started. It will return an exit code indicating the success or failure of the process to run. Exit Codes: http://www.tldp.org/LDP/abs/html/exitcodes.html
Returns: The Exit code
Shell Script¶
-
class
s4.clarity.scripts.
ShellScript
(options)¶ Bases:
s4.clarity.scripts.GenericScript
ShellScript provides the framework for a basic shell script that will communicate with Clarity. It provides all of the functionality of a GenericScript with the addition of a LIMS object.
Creates a new instance of this class and saves the command line options
Parameters: options (argparse.Namespace) – The parsed command line options
StepEpp¶
-
class
s4.clarity.scripts.
StepEPP
(options)¶ Bases:
s4.clarity.scripts.GenericScript
This class forms the base of the scripting for Step EPP scripts run from Clarity. It will provide access to a LIMS object as well as the Step data for the currently running step.
If the log file name that gets passed in over the command line is the limsId clarity assigned to an file it will be automatically uploaded at the end of the step.
Variables: - step (s4.clarity.step.Step) – The Clarity Step to execute the script against.
- lims (LIMS) – The Clarity LIMS object to use for API operations.
Creates a new StepEPP object and initializes the local LIMS and Step objects.
Parameters: options – Parsed command line options -
PREFETCH_INPUTS
= 'inputs'¶
-
PREFETCH_OUTPUTS
= 'outputs'¶
-
PREFETCH_SAMPLES
= 'samples'¶
-
classmethod
add_arguments
(argparser)[source]¶ Configures the Argument Parser to read command line input and store it in the self.options object.
This method can be overrode in sub classes to provide extra arguments specific to the script being written. When this is done it is important to call the parent class add_arguemnts methods so that all arguments are included.
Parameters: parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.
-
prefetch
(*categories)[source]¶ Fetch values for input artifacts, output artifacts, or samples in a batch.
Input and output samples are always an identical set, so ‘samples’ will fetch both.
Note: when only samples are selected, input artifacts will also be fetched. To change this behaviour, supply both ‘outputs’ and ‘samples’ in the categories list.
Parameters: categories (str|list[str]) – List of any number of the strings: ‘inputs’, ‘outputs’, ‘samples’. Returns: a list of all fetched objects Return type: list[ClarityElement]
TriggeredStepEpp¶
-
class
s4.clarity.scripts.
TriggeredStepEPP
(options)¶ Bases:
s4.clarity.scripts.StepEPP
TriggeredStepEPP acts as an EPP with multiple entry points, to allow the developer to group all scripts associated with a step together in a single file. A script implementing this class is intended to be called multiple times in the same step at different stages, with the Action parameter determining which method is called.
Choices for the Action parameter are automatically generated from all class methods starting with
on_
. The Action value is generated by taking the method name, trimming theon_
, and transforming the rest of the name to Pascal-case. For example, an EPP String containing-a TestThing
would attempt to execute a method namedon_test_thing
.- Usage:
python <script.py> -u {username} -p {password} --step-uri {stepURI:v2} -l {compoundOutputFileLuid#} -a <Action>
Our suggested implementation when creating method names is to mirror Clarity’s language for scripts triggered on step transitions, and having button-triggered scripts follow the button label, as shown here:
Action Parameter EPP Method Name BeginningOfStep on_beginning_of_step EndOfStep on_end_of_step PlacementEnter on_placement_enter PlacementExit on_placement_exit PoolingEnter on_pooling_enter PoolingExit on_pooling_exit AddReagentsEnter on_add_reagents_enter AddReagentsExit on_add_reagents_exit RecordDetailsEnter on_record_details_enter RecordDetailsExit on_record_details_exit CalculateQc on_calculate_qc (Record Details buttons example) Ultimately, though, as long as the
on_
rules for method naming is followed, the pattern used in your implementation is up to you.Creates a new StepEPP object and initializes the local LIMS and Step objects.
Parameters: options – Parsed command line options -
classmethod
add_arguments
(argparser)[source]¶ Configures the Argument Parser to read command line input and store it in the self.options object.
This method can be overrode in sub classes to provide extra arguments specific to the script being written. When this is done it is important to call the parent class add_arguemnts methods so that all arguments are included.
Parameters: parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.
-
run
()[source]¶ The run method is called once the arguments are parsed and the logging is started. It will return an exit code indicating the success or failure of the process to run. Exit Codes: http://www.tldp.org/LDP/abs/html/exitcodes.html
Returns: The Exit code
-
triggered_step_actions
= {}¶
UserMessageException¶
-
class
s4.clarity.scripts.
UserMessageException
¶ Bases:
Exception
Stops the currently running EPP and displays a message box to the user. The message box is like other exceptions but will not display a stack trace.
Workflow Test¶
-
class
s4.clarity.scripts.
WorkflowTest
(options)¶ Bases:
s4.clarity.scripts.ShellScript
Creates a new instance of this class and saves the command line options
Parameters: options (argparse.Namespace) – The parsed command line options