spacr.qt.recipes

Settings templates: named, reusable and shareable bundles of settings.

The historical Recipe API, JSON format and storage paths remain compatible.

A lab often uses several sets of settings, each tied to a preparation, such as “Toxo PVM, 40×”. A settings CSV saved in a folder has no name, no record of its module and no record of the spaCR version that wrote it.

A recipe records all four:

• it has a name the user chose;

• it knows its module, so applying a Mask recipe to Measure is refused rather than writing keys that do not apply there;

• it records the spaCR version it was captured with, and applying it under a different one says so and lists the recipe’s settings that the module no longer has;

• it is one file, so sharing it is sending a file.

Storage is ~/.spacr/recipes/<module>/<slug>.json, honouring RECIPE_DIR_ENV — the same shape spacr.macro.macros_dir() uses, so a lab that redirects one redirects both.

The file format is plain JSON:

{
  "spacr_recipe": 1,
  "name": "Toxo PVM, 40x",
  "app_key": "mask",
  "spacr_version": "1.3.6",
  "created": "2026-08-03T22:41:07",
  "notes": "",
  "settings": {"cell_channel": 1, ...}
}

spacr_recipe is a format version, not the spaCR version: the two change for unrelated reasons, so a reader accepts any file whose format version it can read.

Classes

Recipe	One named settings bundle.
RecipeDialog	List, apply, share and delete the recipes for one module.

Functions

apply_recipe(→ int)	Write a recipe's settings into screen. Returns how many landed.
capture_recipe(→ Recipe)	Build a recipe from a screen's current settings.
compatibility_note(→ str)	Describe the recipe's settings that this module does not have.
delete_recipe(→ bool)	Remove a recipe's file. True when something was removed.
install(→ Optional[PySide6.QtWidgets.QToolButton])	Add a Templates button to screen's settings search strip.
install_help_action(→ Optional[PySide6.QtGui.QAction])	Add Settings templates… to the window's Help menu.
install_window_hooks(→ Optional[_StackWatcher])	Wire recipes into a live main window.
list_recipes(→ List[Recipe])	Every readable recipe, newest first.
load_recipe(→ Recipe)	Read one recipe file.
open_recipes(→ RecipeDialog)	Open the recipe dialog for screen.
recipes_dir(→ str)	The folder holding recipes, optionally for one module.
save_recipe(→ str)	Write recipe and return its path.
spacr_version(→ str)	The running spaCR version, or "unknown" if it cannot be read.
version_note(→ str)	What to tell the user about the version gap, or "" if there is none.

Module Contents

class spacr.qt.recipes.Recipe

One named settings bundle.

Parameters:

• name – display name chosen by the user; its slug becomes the file stem when the recipe is saved.

• app_key – key of the module the settings belong to; it picks the recipe’s subfolder and is checked against the screen on apply.

• settings – setting key to value mapping written into the screen.

• spacr_version – spaCR version the recipe was saved with; filled in on save when empty.

• created – ISO-8601 timestamp of creation, to the second; filled in on save when empty and used to sort listings newest first.

• notes – free-text notes stored with the recipe.

• path – file the recipe was loaded from or saved to; not written into the file itself.

classmethod from_json(data: Dict[str, Any], path: str = '') → Recipe

Build a recipe from a parsed file.

Parameters:

data – the parsed JSON mapping; it must carry an integer spacr_recipe format version no newer than this build reads and a settings dict. Missing name falls back to "Untitled".

Raises:

ValueError – when the mapping is not a recipe at all, or is a format version this build does not understand. Both raise an explicit error, so an arbitrary JSON file such as a package.json is not applied as settings.

to_json() → Dict[str, Any]

The on-disk mapping. path is where it lives, not part of it.

class spacr.qt.recipes.RecipeDialog(screen, parent: PySide6.QtWidgets.QWidget | None = None)

Bases: PySide6.QtWidgets.QDialog

List, apply, share and delete the recipes for one module.

Parameters:

• screen – the module screen whose recipes these are. Its app_key is what the list is filtered by, and it becomes the dialog’s parent when none is given.

• parent – parent widget. Defaults to screen.

Build the recipe dialog for one module screen.

Parameters:

• screen – the module screen whose settings recipes are saved and applied; its app_key scopes which recipes are listed.

• parent – parent widget; defaults to screen.

detail_text() → str

The line under the list. Public so tests read what users read.

recipes() → List[Recipe]

The recipes currently listed.

reload() → None

Re-read the module’s recipe folder and repopulate the list.

selected() → Recipe | None

The highlighted recipe, or None.

set_confirmation_runner(runner: Callable[[PySide6.QtWidgets.QMessageBox], Any]) → None

Replace how the version/compatibility confirmation is run.

The default enters the real modal Apply/Cancel loop. Tests inject a runner that inspects the fully configured message box and returns an answer without blocking; a host can use the same seam for a custom presentation.

Parameters:

runner – callable given the configured Apply/Cancel QMessageBox; the recipe is applied only when it returns QMessageBox.Apply.

spacr.qt.recipes.apply_recipe(recipe: Recipe, screen) → int

Write a recipe’s settings into screen. Returns how many landed.

Delegates to AppScreen.apply_settings_dict, which is the same path the settings-CSV import takes — so a recipe reaches the same widgets an imported CSV reaches.

Raises:

ValueError – when the recipe belongs to a different module. It is refused rather than partially applied: the keys that happen to overlap between two modules are exactly the generic ones (src, verbose, n_jobs), so a cross-module apply would write only those and still report success.

Parameters:

• recipe – the recipe to apply; its settings are copied, not mutated.

• screen – the module screen to write into; its app_key must match the recipe’s (when both are set) and it must provide apply_settings_dict.

spacr.qt.recipes.capture_recipe(screen, name: str, notes: str = '') → Recipe

Build a recipe from a screen’s current settings.

Uses SettingsWidgets.collect, so what is captured is exactly what a Run would use — including the defaults the user never touched. Storing every value means the recipe reproduces the same settings after a default changes.

Parameters:

• screen – the module screen to capture; it must have a settings model (_settings_model) or ValueError is raised, and its app_key is stored on the recipe.

• name – display name for the recipe; empty gives "Untitled".

spacr.qt.recipes.compatibility_note(recipe: Recipe, model) → str

Describe the recipe’s settings that this module does not have.

The version gap says that something may have moved; this says what. Reported as a count plus the first four names, so a recipe that differs in many keys gives a short note. The result is empty when there is nothing to report.

Parameters:

• recipe – the bundle.

• model – the screen’s SettingsWidgets.

spacr.qt.recipes.delete_recipe(recipe: Recipe) → bool

Remove a recipe’s file. True when something was removed.

Parameters:

recipe – the recipe whose path is deleted; an empty or missing path removes nothing.

spacr.qt.recipes.install(screen) → PySide6.QtWidgets.QToolButton | None

Add a Templates button to screen’s settings search strip.

The strip is where a settings bundle belongs — directly above the settings it bundles — and it already exists, so no new toolbar is added. Returns None when the screen has no strip (a bespoke screen), or when one is already installed.

Parameters:

screen – the module screen; its _settings_search strip must provide add_trailing_widget. If the screen already has a _recipe_button, that button is returned unchanged.

spacr.qt.recipes.install_help_action(window: PySide6.QtWidgets.QMainWindow) → PySide6.QtGui.QAction | None

Add Settings templates… to the window’s Help menu.

Returns the action, or None when there is no Help menu or one is already installed. The command palette mirrors menu actions, so recipes are also reachable from Ctrl+K.

Parameters:

window – the main window; its menu-bar menu titled “Help” (& ignored) receives the action, before the first separator.

spacr.qt.recipes.install_window_hooks(window: PySide6.QtWidgets.QMainWindow) → _StackWatcher | None

Wire recipes into a live main window.

Called once from spacr.qt.shortcuts.install(). Every failure is logged and swallowed, so a failure to add recipes does not stop the window.

Parameters:

window – the main window; the Help-menu action is added to it and its _stack screen stack is watched so each shown screen gets a Templates button. Without a _stack the result is None.

spacr.qt.recipes.list_recipes(app_key: str | None = None) → List[Recipe]

Every readable recipe, newest first.

Unreadable files are logged and skipped rather than raising: one corrupt file must not make the whole list unopenable.

Parameters:

app_key – restrict to one module.

spacr.qt.recipes.load_recipe(path: str) → Recipe

Read one recipe file.

Parameters:

path – path to a recipe JSON file; it is recorded on the returned recipe.

Raises:

ValueError – on anything that is not a readable recipe.

spacr.qt.recipes.open_recipes(screen, parent: PySide6.QtWidgets.QWidget | None = None) → RecipeDialog

Open the recipe dialog for screen.

Parameters:

screen – the module screen whose recipes are listed and applied, passed to RecipeDialog.

spacr.qt.recipes.recipes_dir(app_key: str | None = None) → str

The folder holding recipes, optionally for one module.

~/.spacr/recipes (or RECIPE_DIR_ENV), with one subfolder per module so a listing is already scoped and a user can hand over a whole module’s worth by copying one directory. Created on first use.

Parameters:

app_key – restrict to one module’s folder.

spacr.qt.recipes.save_recipe(recipe: Recipe, directory: str | None = None) → str

Write recipe and return its path.

Parameters:

• recipe – the bundle. Its spacr_version and created are filled in here when empty, so a caller does not have to set them.

• directory – override the destination (used by export).

spacr.qt.recipes.spacr_version() → str

The running spaCR version, or "unknown" if it cannot be read.

spacr.qt.recipes.version_note(recipe: Recipe, current: str | None = None) → str

What to tell the user about the version gap, or "" if there is none.

Returns a sentence that names both versions, not a boolean, so the user can judge the gap.

Parameters:

• recipe – the bundle about to be applied.

• current – override the running version (tests).