mpylab.tools.configuration_snapshot module

Capture and inspect immutable measurement-graph configuration evidence.

Capturing, verifying, and comparing snapshots only read configuration files. Extraction writes a caller-selected destination. None of these operations initializes communication buses or restores hardware state.

exception mpylab.tools.configuration_snapshot.ConfigurationSnapshotError

Bases: ValueError

Raised when complete measurement-graph configuration evidence cannot be captured.

mpylab.tools.configuration_snapshot.capture_measurement_graph_snapshot(graph, *, strict_ambiguity: bool = True, reject_credentials: bool = True, max_resource_bytes: int | None = 67108864, max_total_bytes: int | None = 268435456) → dict

Capture the files defining a prepared measurement graph.

Parameters:

  • graph (mpylab.tools.mgraph.MGraph) – Graph whose CreateDevices() method has resolved its node INI files. No device initialization is performed by this function.

  • strict_ambiguity (bool, optional) – Reject a reference when multiple search-path candidates exist.

  • reject_credentials (bool, optional) – Reject high-confidence credential fields and private-key material. Ordinary VISA, GPIB, serial, and network addresses are not rejected.

  • max_resource_bytes (int or None, optional) – Maximum size of one resource. None disables the individual limit.

  • max_total_bytes (int or None, optional) – Maximum combined size of unique resources. None disables the total limit.

Returns:

Versioned, pickle-friendly snapshot containing exact resource bytes, hashes, and reference relationships.

Return type:

dict

Raises:

  • ConfigurationSnapshotError – If a resource is missing, ambiguous, unreadable, too large, or appears to contain credentials.

  • RuntimeError – If graph devices have not yet been created and their INI paths are therefore unresolved.

mpylab.tools.configuration_snapshot.compare_measurement_graph_snapshots(expected: dict, actual: dict) → dict

Compare two verified measurement-graph snapshots.

Parameters:

  • expected (mapping) – Snapshots to compare. Their embedded hashes are verified first.

  • actual (mapping) – Snapshots to compare. Their embedded hashes are verified first.

Returns:

Equality flag plus added and removed resources and changes to graph settings or reference relationships.

Return type:

dict

Raises:

ConfigurationSnapshotError – If either snapshot fails verification.

mpylab.tools.configuration_snapshot.extract_measurement_graph_snapshot(snapshot: dict, destination, *, overwrite: bool = False) → dict

Extract a verified snapshot without initializing measurement devices.

Parameters:

  • snapshot (mapping) – Snapshot to verify and extract.

  • destination (path-like) – Directory receiving DOT, INI, data, and custom-driver files. Inline data remain embedded in their original INI content.

  • overwrite (bool, optional) – Replace existing files. By default, an existing file with different content aborts extraction.

Returns:

Mapping from resource identifiers to their primary extracted path. Every safe logical alias is materialized; inline resources map to None because the INI already contains them.

Return type:

dict

Raises:

  • ConfigurationSnapshotError – If verification fails, logical names collide, or a target file exists with different content and overwrite is false.

  • OSError – If the destination cannot be created or written.

mpylab.tools.configuration_snapshot.verify_measurement_graph_snapshot(snapshot: dict) → None

Verify all resource hashes and the configuration digest.

Parameters:

snapshot (mapping) – Measurement-graph snapshot returned by capture_measurement_graph_snapshot().

Raises:

ConfigurationSnapshotError – If the schema is unsupported or stored content does not match its recorded resource or configuration digest.