spacr.restart_state

Persist GUI state across a forced spaCR restart.

The restart record stores the current module, its settings, a summary of active runs, and the locations of any run folders. save() verifies the record before the current process exits, and take() consumes it when the new process starts so that stale state is not restored repeatedly.

Only the interface configuration is restored. Active computations do not resume after a forced restart; output written before the restart remains in the recorded run folders.

Functions

command(→ List[str])	Return the command used to restart the PySide6 application.
describe_running(→ str)	Format active module names and elapsed times for a restart prompt.
discard(→ bool)	Remove the pending restart record.
peek(→ Optional[Dict[str, Any]])	Read the pending restart record without consuming it.
save(, run_folders, saved)	Write and verify a pending restart record.
state_path(→ pathlib.Path)	Return the path used for the pending restart record.
take(→ Optional[Dict[str, Any]])	Consume and return a recent restart record.
warning_text() → str)	Build the confirmation text shown before a forced restart.

Module Contents

spacr.restart_state.command() → List[str]

Return the command used to restart the PySide6 application.

The command uses the active Python interpreter and the explicit spacr.qt entry point, so a forced restart returns to the same GUI without depending on an executable found through PATH.

Returns:

list of str – Command arguments suitable for subprocess.Popen.

spacr.restart_state.describe_running(running: Sequence[Mapping[str, Any]]) → str

Format active module names and elapsed times for a restart prompt.

Parameters:

running – Active-run records. Each record may contain module or name and an elapsed seconds value.

Returns:

str – A comma-separated summary, or an empty string when no named runs are present.

spacr.restart_state.discard() → bool

Remove the pending restart record.

Returns:

bool – True when a record was removed; otherwise False.

spacr.restart_state.peek() → Dict[str, Any] | None

Read the pending restart record without consuming it.

Returns:

dict or None – The saved record, or None when no valid record can be read.

spacr.restart_state.save(*, module: str, settings: Mapping[str, Any] | None = None, running: Sequence[Mapping[str, Any]] = (), run_folders: Sequence[str] = (), saved: str = '') → pathlib.Path | None

Write and verify a pending restart record.

Parameters:

• module – Key of the module to reopen.

• settings – Module settings to restore. Values that JSON cannot encode directly are converted to strings.

• running – Active-run records to display in the restart summary.

• run_folders – Paths that may contain partial output from interrupted runs.

• saved – Optional ISO 8601 timestamp. The current UTC time is used by default.

Returns:

pathlib.Path or None – Path to the verified record, or None when it could not be written and the restart must be cancelled.

Notes

The function logs write errors instead of raising because it is called during shutdown. Callers must not restart when None is returned.

spacr.restart_state.state_path() → pathlib.Path

Return the path used for the pending restart record.

spacr.restart_state.take() → Dict[str, Any] | None

Consume and return a recent restart record.

The saved file is removed before this function returns, including when the record is invalid or older than MAX_AGE_SECONDS.

Returns:

dict or None – A recent restart record, or None when none is available.

spacr.restart_state.warning_text(running: Sequence[Mapping[str, Any]], run_folders: Sequence[str] = ()) → str

Build the confirmation text shown before a forced restart.

The text identifies runs that will stop, explains that settings will be restored, and lists the locations of partial output when available.

Parameters:

• running – Active-run records accepted by describe_running().

• run_folders – Paths that may contain output written before the restart.

Returns:

str – Paragraphs suitable for a restart confirmation dialog.