magscope.scripting

Utilities for registering and executing scripted automation flows.

This module provides the runtime that powers MagScope’s lightweight automation system. Users describe a sequence of actions in a script file by instantiating Script and adding IPC Command instances. The resulting steps are validated against ScriptRegistry to ensure that each call is valid before being executed by ScriptManager.

Only methods decorated with register_script_command() are exposed to the script environment. Script execution runs in its own manager process and communicates with other parts of the application through the standard IPC mechanism.

Attributes

logger

Classes

ScriptStep	Structured representation of a single scripted action.
ScriptCommandRegistration	Metadata binding a script-visible method to its IPC command type.
Script	Container that records the steps of a user-authored script.
ScriptRegistry	Tracks scriptable methods that managers expose to the scripting API.
ScriptStatus	Lifecycle stages of a script managed by ScriptManager.
ScriptManager	Process that coordinates script execution and forwards IPC messages.

Module Contents

magscope.scripting.logger

class magscope.scripting.ScriptStep

Structured representation of a single scripted action.

command: magscope.ipc_commands.Command

wait: bool = False

class magscope.scripting.ScriptCommandRegistration

Metadata binding a script-visible method to its IPC command type.

cls_name: str

meth_name: str

command_type: type[magscope.ipc_commands.Command]

callable: Callable

class magscope.scripting.Script

Container that records the steps of a user-authored script.

steps: list[ScriptStep] = []

append(command: magscope.ipc_commands.Command, *, wait: bool = False)

Append an IPC command to the script.

class magscope.scripting.ScriptRegistry

Tracks scriptable methods that managers expose to the scripting API.

avoided_names = ['sentinel', 'send_ipc']

_methods: dict[type[magscope.ipc_commands.Command], ScriptCommandRegistration]

__call__(command_type: type[magscope.ipc_commands.Command]) → ScriptCommandRegistration

Return the registered callable for command_type.

Raises:

ValueError: If command_type has not been registered.

register_class_methods(cls)

Inspect cls for scriptable methods and add them to the registry.

check_script(script: Iterable[ScriptStep], *, command_registry=None)

Validate a compiled script before it is executed.

Checks include verifying that the method exists, arguments bind against the callable signature, and that reserved flags such as wait have the correct types. When command_registry is provided, the command must also map to a registered IPC handler so that ScriptManager can dispatch it.

static _collect_script_registrations(cls)

Yield scriptable methods declared on cls and its bases.

static get_class_name(cls)

Return the class name for a class or instance.

class magscope.scripting.ScriptStatus

Bases: enum.StrEnum

Lifecycle stages of a script managed by ScriptManager.

EMPTY = 'Empty'

LOADED = 'Loaded'

RUNNING = 'Running'

PAUSED = 'Paused'

FINISHED = 'Finished'

ERROR = 'Error'

class magscope.scripting.ScriptManager

Bases: magscope.processes.ManagerProcessBase

Process that coordinates script execution and forwards IPC messages.

_script: list[ScriptStep] = []

_script_index: int = 0

_script_length: int = 0

script_registry

_script_status: ScriptStatus

_script_waiting: bool = False

_script_sleep_duration: float | None = None

_script_sleep_start: float = 0

setup()

Initialise process state.

Currently no special setup is required, but the hook is retained for symmetry with other ManagerProcessBase implementations.

do_main_loop()

Main loop executed by the process infrastructure.

start_script()

Start the currently loaded script from the beginning.

pause_script()

Pause the running script.

resume_script()

Resume a script that was previously paused.

load_script(path)

Load and validate a script from path.

The script file is executed in an isolated namespace. Exactly one Script instance must be created in that file; its recorded steps are copied locally after validation.

_execute_script_step(step: ScriptStep)

Dispatch a single script step to its owning manager.

update_waiting()

Let the script resume after waiting for a previous step to finish.

start_sleep(duration: float)

Pause the script for duration seconds.

_do_sleep()

Check whether the scripted sleep period has elapsed.

_send_script_step_update(current_step: int | None, *, description: str | None = None)

Notify the GUI of the current script position.

static _format_script_step(step: ScriptStep) → str

Return a user-friendly description of a script step.

_set_script_status(status)

Notify the GUI that the script status has changed.

_handle_script_error(message: str, *, details: str | None)

Report a script error to the GUI and transition to the error state.