BaseScript¶

class lsst.ts.salobj.BaseScript(index, descr)¶

Bases: lsst.ts.salobj.Controller, abc.ABC

Abstract base class for SAL Scripts.

Parameters:	index : `int` Index of SAL Script component. This must be non-zero and should be unique among all loaded SAL scripts (to avoid multiple scripts responding to a command). descr : `str` Short description of what the script does, for operator display.
Raises:	ValueError If index=0. This is prohibited because index=0 would cause the script to respond to commands meant for every other script.
Attributes:	log : `logging.Logger` A logger. done_task : `asyncio.Task` A task that is done when the script has fully executed. final_state_delay : `float` Final delay (in seconds) before exiting. Must be long enough to allow final events to be output. timestamps : `dict` [`lsst.ts.idl.enums.ScriptState`, `float`] Dict of script state: TAI unix timestamp. Used to set timestamp data in the `script` event.

Attributes Summary

`checkpoints`	Get the checkpoints at which to pause and stop.
`domain`
`group_id`	Get the group ID (a `str`), or “” if not set.
`state`	Get the current state.
`state_name`	Get the name of the current `state`.state.

Methods Summary

`amain`([descr])	Run the script from the command line.
`assert_state`(action, states)	Assert that the current state is in `states` and the script is not exiting.
`checkpoint`([name])	Await this at any “nice” point your script can be paused or stopped.
`cleanup`()	Perform final cleanup, if any.
`close`([exception])	Shut down, clean up resources and set done_task done.
`close_tasks`()	Shut down pending tasks.
`configure`(config)	Configure the script.
`do_configure`(data)	Configure the currently loaded script.
`do_resume`(data)	Resume the currently paused script.
`do_run`(data)	Run the script and quit.
`do_setCheckpoints`(data)	Set or clear the checkpoints at which to pause and stop.
`do_setGroupId`(data)	Set or clear the group_id attribute.
`do_setLogLevel`(data)	Set logging level.
`do_stop`(data)	Stop the script.
`get_schema`()	Return a jsonschema to validate configuration, as a `dict`.
`main`([descr])	Start the script from the command line.
`make_from_cmd_line`([descr])	Make a script from command-line arguments.
`next_supplemented_group_id`()	Return the group ID supplemented with a new subgroup.
`put_log_level`()	Output the logLevel event.
`run`()	Run the script.
`set_metadata`(metadata)	Set metadata fields in the provided struct, given the current configuration.
`set_state`([state, reason, keep_old_reason, …])	Set the script state.
`start`()	Finish construction.

Attributes Documentation

checkpoints¶

Get the checkpoints at which to pause and stop.

Returns self.evt_checkpoints.data which has these fields:

pause: checkpoints at which to pause, a regular expression
stop: checkpoints at which to stop, a regular expression

domain¶

group_id¶: Get the group ID (a str), or “” if not set.

state¶

Get the current state.

Returns self.evt_state.data, which has these fields:

state: lsst.ts.idl.enums.Script.ScriptState

The current state.
last_checkpoint: str

Name of most recently seen checkpoint.
reason: str

Reason for this state, if any.

state_name¶: Get the name of the current state.state.

Methods Documentation

classmethod amain(descr=None)¶

Run the script from the command line.

Parameters:	descr : `str` (optional) Short description of what the script does, for operator display. Leave at None if the script already has a description, which is the most common case. Primarily intended for unit tests, e.g. running `TestScript`.

Notes

The final return code will be:

0 if final state is lsst.ts.idl.enums.Script.ScriptState.DONE or lsst.ts.idl.enums.Script.ScriptState.STOPPED
1 if final state is lsst.ts.idl.enums.Script.ScriptState.FAILED
2 otherwise (which should never happen)

assert_state(action, states)¶

Assert that the current state is in states and the script is not exiting.

Parameters:	action : `string` Description of what you want to do. states : `list` [`lsst.ts.idl.enums.Script.ScriptState`] Allowed states.

checkpoint(name='')¶

Await this at any “nice” point your script can be paused or stopped.

Parameters:	name : `str` (optional) Name of checkpoint; “” if it has no name.
Raises:	RuntimeError If the state is not `ScriptState.RUNNING`. This likely means you called checkpoint from somewhere other than `run`. RuntimeError If `_run_task` is `None` or done. This probably means your code incorrectly set the state.

cleanup()¶

Perform final cleanup, if any.

This method is always called as the script state is exiting (unless the script process is aborted by SIGTERM or SIGKILL).

close(exception=None)¶

Shut down, clean up resources and set done_task done.

May be called multiple times. The first call closes the Controller; subsequent calls wait until the Controller is closed.

Subclasses should override close_tasks instead of close, unless you have a good reason to do otherwise.

Parameters:	exception : `Exception` (optional) The exception that caused stopping, if any, in which case the `self.done_task` exception is set to this value. Specify `None` for a normal exit, in which case the `self.done_task` result is set to `None`.

Notes

Removes the SAL log handler, calls close_tasks to stop all background tasks, pauses briefly to allow final SAL messages to be sent, then closes the dds domain.

close_tasks()¶

Shut down pending tasks. Called by close.

Perform all cleanup other than disabling logging to SAL and closing the dds domain.

configure(config)¶

Configure the script.

Parameters:	config : `types.SimpleNamespace` Configuration.

Notes

This method is called by do_configure`. The script state will be ScriptState.UNCONFIGURED.

do_configure(data)¶

Configure the currently loaded script.

Parameters:	data : `cmd_configure.DataType` Configuration.
Raises:	base.ExpectedError If `self.state.state` is not `lsst.ts.idl.enums.Script.ScriptState.UNCONFIGURED`.

Notes

This method does the following:

Parse the config field as yaml-encoded dict and validate it (including setting default values).
Call configure.
Set the pause and stop checkpoints.
Set the log level if data.logLevel != 0.
Call set_metadata.
Output the metadata event.
Change the script state to lsst.ts.idl.enums.Script.ScriptState.CONFIGURED.

do_resume(data)¶

Resume the currently paused script.

Parameters:	data : `cmd_resume.DataType` Ignored.
Raises:	base.ExpectedError If `self.state.state` is not `lsst.ts.idl.enums.Script.ScriptState.PAUSED`.

do_run(data)¶

Run the script and quit.

The script must have been configured and the group ID set.

Parameters:	data : `cmd_run.DataType` Ignored.
Raises:	base.ExpectedError If `self.state.state` is not `lsst.ts.idl.enums.Script.ScriptState.CONFIGURED`. If `self.group_id` is blank.

do_setCheckpoints(data)¶

Set or clear the checkpoints at which to pause and stop.

This command is deprecated. Please set the checkpoints using the configure command.

Parameters:	data : `cmd_setCheckpoints.DataType` Names of checkpoints for pausing and stopping, each a single regular expression; “” for no checkpoints, “.*” for all.
Raises:	base.ExpectedError If `self.state.state` is not one of: `lsst.ts.idl.enums.Script.ScriptState.UNCONFIGURED` `lsst.ts.idl.enums.Script.ScriptState.CONFIGURED` `lsst.ts.idl.enums.Script.ScriptState.RUNNING` `lsst.ts.idl.enums.Script.ScriptState.PAUSED`

do_setGroupId(data)¶

Set or clear the group_id attribute.

The script must be in the Configured state. This command may be called multiple times. It is typically called when the script reaches the top position on the script queue.

Parameters:	data : `cmd_setGroupId.DataType` Group ID, or “” to clear the group ID.
Raises:	base.ExpectedError If `state.state` is not `lsst.ts.idl.enums.Script.ScriptState.CONFIGURED`.

do_setLogLevel(data)¶

Set logging level.

Parameters:	data : `cmd_setLogLevel.DataType` Logging level.

do_stop(data)¶

Stop the script.

Parameters:	data : `cmd_stop.DataType` Ignored.

Notes

This is a no-op if the script is already exiting. This does not wait for _exit to run.

classmethod get_schema()¶

Return a jsonschema to validate configuration, as a dict.

Please provide default values for all fields for which defaults make sense. This makes the script easier to use.

If your script has no configuration then return None, in which case the config field of the configure command must be an empty string.

classmethod main(descr=None)¶

Start the script from the command line.

Parameters:	descr : `str` (optional) Short description of what the script does, for operator display. Leave at None if the script already has a description, which is the most common case. Primarily intended for unit tests, e.g. running `TestScript`.

Notes

The final return code will be:

0 if final state is lsst.ts.idl.enums.Script.ScriptState.DONE or lsst.ts.idl.enums.Script.ScriptState.STOPPED
1 if final state is lsst.ts.idl.enums.Script.ScriptState.FAILED
2 otherwise (which should never happen)

classmethod make_from_cmd_line(descr=None)¶

Make a script from command-line arguments.

Return None if --schema specified.

Parameters:	descr : `str` (optional) Short description of what the script does, for operator display. Leave at None if the script already has a description, which is the most common case. Primarily intended for unit tests, e.g. running `TestScript`.

Notes

The final return code will be:

0 if final state is lsst.ts.idl.enums.Script.ScriptState.DONE or lsst.ts.idl.enums.Script.ScriptState.STOPPED
1 if final state is lsst.ts.idl.enums.Script.ScriptState.FAILED
2 otherwise (which should never happen)

next_supplemented_group_id()¶

Return the group ID supplemented with a new subgroup.

The returned string has this format: f”{self.group_id}#{subgroup_id}”, where subgroup_id is an integer that starts at 1 and is incremented for every call to this method.

Raises:	RuntimeError If there is no group ID.

put_log_level()¶: Output the logLevel event.

run()¶

Run the script.

Your subclass must provide an implementation, as follows:

At points where you support pausing call checkpoint.
Raise an exception on error. Raise base.ExpectedError to avoid logging a traceback.

Notes

This method is only called when the script state is ScriptState.CONFIGURED. The remaining state transitions are handled automatically.

set_metadata(metadata)¶

Set metadata fields in the provided struct, given the current configuration.

Parameters:	metadata : `self.evt_metadata.DataType()` Metadata to update. Set those fields for which you have useful information.

Notes

This method is called after configure by do_configure. The script state will be ScriptState.UNCONFIGURED.

set_state(state=None, reason=None, keep_old_reason=False, last_checkpoint=None, force_output=False)¶

Set the script state.

Parameters:

state : ScriptState or int (optional): New state, or None if no change
reason : str (optional): Reason for state change. None for no new reason.
keep_old_reason : bool: If True, keep old reason; append the reason argument after “;” if it is is a non-empty string. If False replace with reason, or “” if reason is None.
last_checkpoint : str (optional): Name of most recently seen checkpoint. None for no change.
force_output : bool (optional): If True the output even if not changed.

start()¶: Finish construction.

Navigation

BaseScript¶