capa.config¶

@classmethod
def load(cls, path: str | Path) -> ConfigDocument:
    """Open an experiment YAML/TOML; resolve hardware/method refs.

    Mirrors :meth:`ExperimentConfig.load`'s file-ref rules: when
    ``hardware:`` or ``method:`` is a string, treat it as a path
    relative to the experiment file's directory. The presence /
    absence of those refs determines ``hardware_mode`` /
    ``method_mode``.
    """
    source = Path(path).resolve()
    data = _load_structured_file(source)
    if not isinstance(data, dict):
        raise ConfigError(f"{source}: top-level must be a mapping")
    format_ = _detect_format(source)

    doc = cls(
        experiment_path=source,
        experiment_format=format_,
    )
    doc.experiment_payload = dict(data)

    # Hardware: required.
    hw_ref = doc.experiment_payload.pop("hardware", None)
    if isinstance(hw_ref, str):
        hw_path = _resolve(hw_ref, source.parent)
        doc.hardware_path = hw_path
        doc.hardware_format = _detect_hardware_format(hw_path)
        doc.hardware_mode = "external"
        doc.hardware_payload = dict(_load_structured_file(hw_path))
    elif isinstance(hw_ref, dict):
        doc.hardware_mode = "inline"
        doc.hardware_payload = dict(hw_ref)
    elif hw_ref is None:
        raise ConfigError(f"{source}: missing required field 'hardware'")
    else:
        raise ConfigError(
            f"{source}: 'hardware' must be a string ref or mapping, got {type(hw_ref).__name__}"
        )

    # Method: optional. Three modes (external / inline / none).
    method_ref = doc.experiment_payload.pop("method", None)
    if isinstance(method_ref, str):
        method_path = _resolve(method_ref, source.parent)
        doc.method_path = method_path
        doc.method_format = "toml"
        doc.method_mode = "external"
        doc.method_payload = dict(_load_structured_file(method_path))
    elif isinstance(method_ref, dict):
        doc.method_mode = "inline"
        doc.method_payload = dict(method_ref)
    else:
        doc.method_mode = "none"
        doc.method_payload = None

    return doc

@classmethod
def load_hardware_only(cls, path: str | Path) -> ConfigDocument:
    """Open a bare hardware TOML; produce a minimal experiment payload.

    Used by the Setup tab when the operator wants to author hardware
    in isolation. The experiment payload is left empty; the Setup
    tab fills in operator / sample / procedure stubs as the operator
    edits.
    """
    source = Path(path).resolve()
    data = _load_structured_file(source)
    if not isinstance(data, dict):
        raise ConfigError(f"{source}: top-level must be a mapping")
    return cls(
        hardware_path=source,
        hardware_format="toml",
        hardware_mode="external",
        hardware_payload=dict(data),
        method_mode="none",
    )

def composed_payload(self) -> dict[str, Any]:
    """Re-inline hardware / method into a single experiment dict.

    The returned dict is what :class:`~capa.experiment.config.ExperimentConfig`
    :meth:`model_validate` expects: a single mapping with ``hardware``
    as a nested mapping and ``method`` either nested, absent, or
    nested-from-an-inline-method. Source-path bookkeeping is
    re-attached as the (excluded-from-serialisation) fields on the
    model so callers that still go through :meth:`load` see the same
    ``hardware_source_path`` / ``method_source_path`` they always did.
    """
    composed: dict[str, Any] = dict(self.experiment_payload)
    composed["hardware"] = dict(self.hardware_payload)
    if self.method_mode != "none" and self.method_payload is not None:
        composed["method"] = dict(self.method_payload)
    if self.method_path is not None:
        composed["method_source_path"] = self.method_path
    if self.hardware_path is not None:
        composed["hardware_source_path"] = self.hardware_path
    return composed

def build_config(self) -> Any:
    """Validate payloads into an :class:`ExperimentConfig`.

    Local import to break the circular dep:
    ``capa.experiment.config`` imports nothing from ``capa.config``;
    this module imports from ``capa.experiment.config``.
    """
    from capa.experiment.config import ExperimentConfig  # noqa: PLC0415

    composed = self.composed_payload()
    try:
        return ExperimentConfig.model_validate(composed)
    except Exception as exc:
        src = self.experiment_path or self.hardware_path
        label = str(src) if src else "<unsaved>"
        raise ConfigError(f"{label}: {exc}") from exc

def save(self) -> None:
    """Atomic multi-file save back to the loaded paths.

    For each target file: write ``<path>.tmp`` in the same directory,
    then ``os.replace()`` into place. On any failure, delete already-
    written ``.tmp`` files. Original files remain intact when any
    member of the save set fails.

    Pre-condition: every target path must already be set (use
    :meth:`save_as` for first-time writes).
    """
    plan = self._save_plan()
    self._execute_save_plan(plan)

def save_as(self, layout: SourceLayout) -> None:
    """Save to a new layout; updates ``self`` in place on success.

    Layout transitions (inline ↔ external for hardware / method) are
    applied here; the document does not silently change them on
    :meth:`save`.
    """
    # Apply layout to a working copy of the document, then save.
    prev = (
        self.experiment_path,
        self.experiment_format,
        self.hardware_path,
        self.hardware_format,
        self.hardware_mode,
        self.method_path,
        self.method_format,
        self.method_mode,
    )
    try:
        self.experiment_path = layout.experiment_path
        self.experiment_format = layout.experiment_format
        self.hardware_path = layout.hardware_path
        self.hardware_format = layout.hardware_format
        self.hardware_mode = layout.hardware_mode
        self.method_path = layout.method_path
        self.method_format = layout.method_format
        self.method_mode = layout.method_mode
        plan = self._save_plan()
        self._execute_save_plan(plan)
    except Exception:
        (
            self.experiment_path,
            self.experiment_format,
            self.hardware_path,
            self.hardware_format,
            self.hardware_mode,
            self.method_path,
            self.method_format,
            self.method_mode,
        ) = prev
        raise

def extract_hardware_inline_to_file(self, hardware_path: Path) -> None:
    """Move inline hardware to an external file (without writing yet).

    Only flips the mode and records the path; call :meth:`save` to
    commit.
    """
    if self.hardware_mode != "inline":
        raise ConfigError("extract_hardware_inline_to_file: hardware is already external")
    self.hardware_path = Path(hardware_path).resolve()
    self.hardware_format = "toml"
    self.hardware_mode = "external"

def inline_hardware_from_file(self) -> None:
    """Inline a currently-external hardware file (without writing yet)."""
    if self.hardware_mode != "external":
        raise ConfigError("inline_hardware_from_file: hardware is already inline")
    self.hardware_mode = "inline"
    self.hardware_path = None
    self.hardware_format = None