SequenceCollection

class caqtus.session.SequenceCollection(*args, **kwargs)

Bases: Protocol

A collection of sequences inside a session.

This abstract class defines the interface to read and write sequences in a session. Objects of this class provide methods for full access to read/write operations on sequences and their shots. However, they are not meant to be convenient to use directly in user code. Instead, consider using the higher-level API provided by the caqtus.session.Sequence and caqtus.session.Shot classes to access data from sequences and shots.

property parent_session: ExperimentSession: The session that this collection belongs to.

abstractmethod get_contained_sequences( path: PureSequencePath, ) → Success[Set[PureSequencePath]] | Failure[PathNotFoundError]

Return the descendants of this path that are sequences.

The current path is included in the result if it is a sequence.

abstractmethod get_global_parameters( path: PureSequencePath, ) → Success[ParameterNamespace] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[SequenceNotLaunchedError]

Get the global parameters that were used by this sequence.

Raises:

RuntimeError – If the sequence is in draft mode, since the global parameters
are only set once the sequence has entered the PREPARING state. –

abstractmethod get_iteration_configuration( sequence: PureSequencePath, ) → IterationConfiguration: Return a copy of the iteration configuration for this sequence.

abstractmethod set_iteration_configuration( sequence: PureSequencePath, iteration_configuration: IterationConfiguration, ) → None | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[SequenceNotEditableError]: Set the iteration configuration for this sequence.

abstractmethod get_time_lanes( sequence_path: PureSequencePath, ) → TimeLanes | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError]: Return a copy of the time lanes for this sequence.

abstractmethod set_time_lanes( sequence_path: PureSequencePath, time_lanes: TimeLanes, ) → None | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[SequenceNotEditableError]: Set the time lanes that define how a shot is run for this sequence.

abstractmethod get_device_configurations( path: PureSequencePath, ) → Success[Mapping[DeviceName, DeviceConfiguration]] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[SequenceNotLaunchedError]: Get the device configurations that are used by this sequence.

abstractmethod create( path: PureSequencePath, iteration_configuration: IterationConfiguration, time_lanes: TimeLanes, ) → Success[None] | Failure[PathIsSequenceError] | Failure[PathHasChildrenError]

Create a new sequence at the given path.

Returns:: If the path already exists and is a sequence. PathHasChildrenError: If the path already exists and has children.
Return type:: PathIsSequenceError

abstractmethod get_exception( path: PureSequencePath, ) → Success[TracebackSummary | None] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[SequenceNotCrashedError]

Return the exceptions that occurred while running the sequence.

Returns:

A result wrapping the exceptions that occurred while running the sequence.

Even if the sequence is in the CRASHED state, there may not be any exceptions captured. In this case, the result will be None.

abstractmethod set_preparing( path: PureSequencePath, device_configurations: Mapping[DeviceName, DeviceConfiguration], global_parameters: ParameterNamespace, ) → Success[None] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[InvalidStateTransitionError]

Set a sequence to the PREPARING state.

Parameters:

path – The path to the sequence to prepare.
device_configurations – The configurations of the devices that were used to run this sequence.
global_parameters – The parameters used to run the sequence.

abstractmethod set_running( path: PureSequencePath, start_time: datetime | Literal['now'], ) → Success[None] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[InvalidStateTransitionError]

Set a sequence to the RUNNING state.

Parameters:

path – The path to the sequence.
start_time – The time at which the sequence started running. Must be a timezone-aware datetime object.

abstractmethod set_finished( path: PureSequencePath, stop_time: datetime | Literal['now'], ) → Success[None] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[InvalidStateTransitionError]

Set a sequence to the FINISHED state.

Parameters:

path – The path to the sequence.
stop_time – The time at which the sequence stopped running. Must be a timezone-aware datetime object.

abstractmethod set_interrupted( path: PureSequencePath, stop_time: datetime | Literal['now'], ) → Success[None] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[InvalidStateTransitionError]

Set a sequence to the INTERRUPTED state.

Parameters:

path – The path to the sequence.
stop_time – The time at which the sequence was interrupted. Must be a timezone-aware datetime object.

abstractmethod set_crashed( path: PureSequencePath, tb_summary: TracebackSummary, stop_time: datetime | Literal['now'], ) → Success[None] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[InvalidStateTransitionError]

Set the sequence to the CRASHED state.

Parameters:

path – The path of the sequence to set to the CRASHED state.
tb_summary – A summary of the error that caused the sequence to crash. This summary will be saved with the sequence.
stop_time – The time at which the sequence crashed. Must be a timezone-aware datetime object.

abstractmethod reset_to_draft( path: PureSequencePath, ) → Success[None] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError] | Failure[InvalidStateTransitionError]: Reset the sequence to the DRAFT state.

Warning

This method removes all data associated to the sequence.

abstractmethod get_shots( path: PureSequencePath, ) → Success[list[ShotId]] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError]: Return the shots that belong to this sequence.

abstractmethod get_shot_data_by_label( data: DataId, ) → Data

Return the data with the given label for the shot at the given index.

Raises:

PathNotFoundError – If the path does not exist in the session.
PathIsNotSequenceError – If the path is not a sequence.
ShotNotFoundError – If the shot does not exist in the sequence.
DataNotFoundError – If the data with the given label does not exist in the
shot. –

get_shot_data_by_labels( path: PureSequencePath, shot_index: int, data_labels: Set[DataLabel], ) → Mapping[DataLabel, TypeAliasForwardRef('Data')]

Return the data with the given labels for the shot at the given index.

This method is equivalent to calling get_shot_data_by_label() for each label in the set, but can be faster.

Raises:

PathNotFoundError – If the path does not exist in the session.
PathIsNotSequenceError – If the path is not a sequence.
ShotNotFoundError – If the shot does not exist in the sequence.
DataNotFoundError – If one of the data labels does not exist in the shot.

abstractmethod get_sequences_in_state( state: State, ) → Iterable[PureSequencePath]: Return all sequences in the given state.

get_parameter_schema( path: PureSequencePath, ) → Success[ParameterSchema] | Failure[PathNotFoundError] | Failure[PathIsNotSequenceError]: Return the parameter schema for this sequence.