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.

Two further records live in the preference store rather than in a file. The last session (module, its settings and its folder) is written while spaCR runs and when it closes as a local recovery snapshot. Ordinary launches open Home; only an explicit restart restores the saved interface. Settings drafts hold the unsaved settings of every open module; they are cleared on a clean exit, so a draft found at start-up means the previous run ended without closing.

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]])	Read a pending restart record and attempt to remove its file.
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.

A frozen application restarts its bundled executable directly, without Python interpreter flags. An unfrozen installation uses the active Python interpreter and the explicit spacr.qt entry point. Both routes return 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

Read a pending restart record and attempt to remove its file.

Attempt to remove the saved file after reading it, including when no valid dictionary was read. A failed removal does not prevent a dictionary from being returned. A dictionary is rejected as expired only when its parseable saved timestamp is older than MAX_AGE_SECONDS; missing or invalid timestamps are not treated as expired.

Returns:

dict or None A readable saved dictionary not known to be expired, or None if no – such dictionary 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.