BaseScript#

class lsst.ts.salobj.BaseScript(index, descr, help='')#

Bases: Controller, 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.

  • help (str, optional) – Detailed help for the script. Markdown formatting is encouraged. This need not duplicate descriptions in the configuration schema.

Raises:

ValueError – If index=0. This is prohibited because index=0 would cause the script to respond to commands meant for every other script.

log#

A logger.

Type:

logging.Logger

done_task#

A task that is done when the script has fully executed.

Type:

asyncio.Task

timestamps#

Dict of script state: TAI unix timestamp. Used to set timestamp data in the script event.

Type:

dict [lsst.ts.xml.enums.ScriptState, float]

Attributes Summary

checkpoints

Get the checkpoints at which to pause and stop.

group_id

Get the group ID (a str), or "" if not set.

obs_id

Get the block 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(**kwargs)

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_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_stop(data)

Stop the script.

get_schema()

Return a jsonschema to validate configuration, as a dict.

make_from_cmd_line(**kwargs)

Make a script from command-line arguments.

next_supplemented_group_id()

Return the group ID supplemented with a new subgroup.

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.

signal_handler()

Handle termination signals.

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

group_id#

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

obs_id#

Get the block ID (a str), or “” if not set.

state#

Get the current state.

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

  • state: lsst.ts.xml.enums.Script.ScriptState

    The current state.

  • lastCheckpoint: str

    Name of most recently seen checkpoint.

  • reason: str

    Reason for this state, if any.

  • numCheckpoints: int

    The number of checkpoints seen.

state_name#

Get the name of the current state.state.

Methods Documentation

async classmethod amain(**kwargs)#

Run the script from the command line.

Parameters:

kwargs (Any) – Keyword arguments for the script constructor. Must not include index. Ignored (other than testing for index) if the command specifies --schema.

Return type:

None

Notes

The final return code will be:

  • 0 if final state is lsst.ts.xml.enums.Script.ScriptState.DONE or lsst.ts.xml.enums.Script.ScriptState.STOPPED.

  • 1 if final state is anything else, or if script.done_task is an exception (which would be raised by the script’s cleanup code).

Issues a RuntimeWarning if script.done_task is an exception and the final script state is anything other than Failed. This should never happen.

Raises:

RuntimeError – If kwargs includes index.

assert_state(action, states)#

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

Parameters:

  • action (str) – Description of what you want to do.

  • states (list [lsst.ts.xml.enums.Script.ScriptState]) – Allowed states.

Return type:

None

async 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.

Return type:

None

async cleanup()#

Perform final cleanup, if any.

This method is called as the script state is exiting, unless the script had not yet started to run, or the script process is aborted by SIGTERM or SIGKILL.

Return type:

None

async close_tasks()#

Shut down pending tasks. Called by close.

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

Return type:

None

abstract async configure(config)#

Configure the script.

Parameters:

config (types.SimpleNamespace) – Configuration.

Return type:

None

Notes

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

async 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.xml.enums.Script.ScriptState.UNCONFIGURED.

Notes

Return type:

None

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.xml.enums.Script.ScriptState.CONFIGURED.

async 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.xml.enums.Script.ScriptState.PAUSED.

Return type:

None

async 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.xml.enums.Script.ScriptState.CONFIGURED. If self.group_id is blank.

Return type:

None

async 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.xml.enums.Script.ScriptState.UNCONFIGURED * lsst.ts.xml.enums.Script.ScriptState.CONFIGURED * lsst.ts.xml.enums.Script.ScriptState.RUNNING * lsst.ts.xml.enums.Script.ScriptState.PAUSED

Return type:

None

async 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.xml.enums.Script.ScriptState.CONFIGURED.

Return type:

None

async do_stop(data)#

Stop the script.

Parameters:

data (cmd_stop.DataType) – Ignored.

Return type:

None

Notes

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

abstract 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.

Return type:

dict[str, Any] | None

classmethod make_from_cmd_line(**kwargs)#

Make a script from command-line arguments.

Return None if --schema specified.

Parameters:

kwargs (Any) – Keyword arguments for the script constructor. Must not include index.

Raises:

RuntimeError – If kwargs includes index.

Return type:

BaseScript | None

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.

Return type:

str

abstract async run()#

Run the script.

Your subclass must provide an implementation, as follows: :rtype: None

Notes

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

abstract 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.

Return type:

None

Notes

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

async set_state(state=None, reason=None, keep_old_reason=False, 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.

  • force_output (bool, optional) – If true the output even if not changed.

Return type:

None

Notes

The lastCheckpoint field is set from self.last_checkpoint, and the numCheckpoints field is set from self.num_checkpoints.

signal_handler()#

Handle termination signals.

Return type:

None

async start()#

Finish construction.

Return type:

None