Scan Events

The typed event hierarchy emitted by the scan engine. Every state transition, every device command, every error, and every dialog request is delivered as an instance of one of these classes through the on_event callback registered with ScanManager.

The narrative description of when each event fires and how to consume them lives at Architecture — Event vocabulary. This page is the formal API.

ScanState

The lifecycle states a scan can be in. Inherits str so values serialise naturally to JSON and log messages.

Bases: str, Enum

Lifecycle state of a scan.

Inherits str so values serialise naturally to JSON / log messages.

Attributes:

Name	Type	Description
IDLE
INITIALIZING
RUNNING
PAUSED_ON_ERROR
STOPPING
DONE
ABORTED

Attributes

IDLE class-attribute instance-attribute

IDLE = 'idle'

INITIALIZING class-attribute instance-attribute

INITIALIZING = 'initializing'

RUNNING class-attribute instance-attribute

RUNNING = 'running'

PAUSED_ON_ERROR class-attribute instance-attribute

PAUSED_ON_ERROR = 'paused_on_error'

STOPPING class-attribute instance-attribute

STOPPING = 'stopping'

DONE class-attribute instance-attribute

DONE = 'done'

ABORTED class-attribute instance-attribute

ABORTED = 'aborted'

Base event

Base class for all scan events.

Parameters:

Name	Type	Description	Default
timestamp	float	Wall-clock time of the event in seconds since the epoch (time.time()). Set automatically if not provided.	time()

Attributes:

Name	Type	Description
timestamp	float

Attributes

timestamp class-attribute instance-attribute

timestamp: float = field(default_factory=time)

Functions

Lifecycle events

Bases: ScanEvent

Emitted at every :class:ScanState transition.

Parameters:

Name	Type	Description	Default
state	ScanState	The state transitioned to.	IDLE
total_shots	int	Total number of shots in the scan (shots_per_step × steps). Non-zero only on the INITIALIZING event; zero on all others. Consumers should cache this value on the INITIALIZING event and use it to compute progress from subsequent :class:ScanStepEvent s.	0

Attributes:

Name	Type	Description
state	ScanState
total_shots	int
timestamp	float

Attributes

state class-attribute instance-attribute

state: ScanState = IDLE

total_shots class-attribute instance-attribute

total_shots: int = 0

timestamp class-attribute instance-attribute

timestamp: float = field(default_factory=time)

Functions

Step progress

Bases: ScanEvent

Emitted at the start and completion of each scan step.

Parameters:

Name	Type	Description	Default
step_index	int	Zero-based index of the current step.	0
total_steps	int	Total number of steps in the scan.	0
shots_completed	int	Cumulative shots logged across all completed steps so far. Together with ScanLifecycleEvent.total_shots this lets consumers compute a shot-level progress fraction without polling.	0
phase	Literal['started', 'completed']	"started" fires before the device set; "completed" fires after acquisition for that step has finished.	'started'

Attributes:

Name	Type	Description
step_index	int
total_steps	int
shots_completed	int
phase	Literal['started', 'completed']
timestamp	float

Attributes

step_index class-attribute instance-attribute

step_index: int = 0

total_steps class-attribute instance-attribute

total_steps: int = 0

shots_completed class-attribute instance-attribute

shots_completed: int = 0

phase class-attribute instance-attribute

phase: Literal['started', 'completed'] = 'started'

timestamp class-attribute instance-attribute

timestamp: float = field(default_factory=time)

Functions

Device command outcomes

Bases: ScanEvent

Emitted for every device command issued by the scan engine.

Parameters:

Name	Type	Description	Default
device	str	Device name (e.g. "U_ESP_JetXYZ").	''
variable	str	Variable name (e.g. "Position.Axis 2").	''
outcome	Literal['sent', 'accepted', 'rejected', 'failed', 'timeout']	Result of the command attempt. "sent" — command dispatched; response not yet known. "accepted" — device acknowledged the command. "rejected" — :class:GeecsDeviceCommandRejected raised. "failed" — :class:GeecsDeviceCommandFailed raised. "timeout" — :class:GeecsDeviceExeTimeout raised.	'sent'

Attributes:

Name	Type	Description
device	str
variable	str
outcome	Literal['sent', 'accepted', 'rejected', 'failed', 'timeout']
timestamp	float

Attributes

device class-attribute instance-attribute

device: str = ''

variable class-attribute instance-attribute

variable: str = ''

outcome class-attribute instance-attribute

outcome: Literal['sent', 'accepted', 'rejected', 'failed', 'timeout'] = 'sent'

timestamp class-attribute instance-attribute

timestamp: float = field(default_factory=time)

Functions

Errors and restore failures

Bases: ScanEvent

Emitted when the engine encounters a recoverable or fatal error.

Parameters:

Name	Type	Description	Default
message	str	Human-readable description of what went wrong.	''
recoverable	bool	True if the scan can continue (e.g. a skipped step); False if the scan is about to abort.	True
exc	Optional[BaseException]	Originating exception, if available.	None

Attributes:

Name	Type	Description
message	str
recoverable	bool
exc	Optional[BaseException]
timestamp	float

Attributes

message class-attribute instance-attribute

message: str = ''

recoverable class-attribute instance-attribute

recoverable: bool = True

exc class-attribute instance-attribute

exc: Optional[BaseException] = None

timestamp class-attribute instance-attribute

timestamp: float = field(default_factory=time)

Functions

Bases: ScanEvent

Emitted once per device that could not be restored after a scan.

The GUI accumulates these and shows a single warning dialog on the ScanLifecycleEvent(DONE) transition.

Parameters:

Name	Type	Description	Default
device	str	Device name that failed to restore.	''
message	str	Description of the failure (exception message or context).	''

Attributes:

Name	Type	Description
device	str
message	str
timestamp	float

Attributes

device class-attribute instance-attribute

device: str = ''

message class-attribute instance-attribute

message: str = ''

timestamp class-attribute instance-attribute

timestamp: float = field(default_factory=time)

Functions

Dialog requests

Bases: ScanEvent

Carries a device-error dialog request across the worker→consumer boundary.

In Block 6 this event is emitted but the GUI still drains dialog_queue as before. In Block 7 the GUI callback receives this event and posts it to the Qt main thread via QMetaObject.invokeMethod; dialog_queue is removed at that point.

The consumer must call request.response_event.set() after writing the user's choice into request.abort[0]; the worker thread is blocking on request.response_event.wait().

Parameters:

Name	Type	Description	Default
request	Optional[DialogRequest]	The :class:~geecs_scanner.engine.dialog_request.DialogRequest object shared between the worker and the consumer.	None

Attributes:

Name	Type	Description
request	Optional[DialogRequest]
timestamp	float

Attributes

request class-attribute instance-attribute

request: Optional[DialogRequest] = None

timestamp class-attribute instance-attribute

timestamp: float = field(default_factory=time)

Functions