early_boot

Run this FIRST, before anything else (even logging).

• Reads machine params from ~/.clearmap/machine_params_v<major>_<minor>.cfg

• Patches tempfile’s default directory ASAP (if configured)

Warning

Any module imported here should not read tempfile.tempdir to avoid a race condition in setting it.

class BootResult

Bases: TypedDict

cfg_ensured: bool

desktop_entry_ok: bool

first_run: bool

tmp_dir: str | None

class MachineConfig

Bases: object

Minimal, side-effect-free reader for machine config. Caches the parsed file; exposes DEFAULT section as a mapping.

static machine_cfg_path() → Path

get(key: str, default: str | int | float | bool | None = None) → str | None

patch_tmp(*, allow_prompt: bool = True) → str | None

If temp_folder is set (and not ‘null’), ensure it exists, then patch os env TMP/TEMP/TMPDIR and tempfile.tempdir. Returns the resolved folder (or None).

prompt_tmp_folder()

property cfg_path: Path

property defaults: Dict[str, Any]

property start_full_screen: bool

property verbosity: str

first_boot(*, allow_prompt: bool = True) → BootResult

Call this at the very beginning of your entry point. It will: - ensure the per-user config exists - patch temp dir (may prompt unless headless or allow_prompt=False) - run migrations (if version changed) - ensure desktop entry on Linux (best-effort) - persist a small boot state stamp

prompt_machine_params() → bool

Try to open the Preferences dialog so the user can fill machine params. Returns True if the dialog opened and was accepted, False otherwise. Falls back gracefully in headless/CI.