qdk_chemistry.ui.io module

File I/O utilities for QDK Chemistry data objects.

qdk_chemistry.ui.io.current_project_dir()

Return the absolute project directory validated for this execution context.

Return type:

Path | None

qdk_chemistry.ui.io.resolve_project_file(filename, *, allow_nested=False, allow_absolute=False)

Resolve a client-provided filename inside the current project sandbox.

Absolute paths, traversal components, Windows drive or UNC paths, and symlinks that resolve outside the project are rejected.

Parameters:

  • filename (str | Path) – Project-relative filename to resolve.

  • allow_nested (bool) – Whether ordinary nested path components are accepted.

  • allow_absolute (bool) – Whether an internal absolute path may be revalidated.

Return type:

Path

Returns:

An absolute path contained by the current project directory.

Raises:

  • RuntimeError – If called outside a validated project context.

  • ValueError – If the filename is invalid or escapes the project.

qdk_chemistry.ui.io.check_output_path_exists(filename, data_class=None)[source]

Check whether an exact output path already exists with valid content.

Parameters:

  • filename (str | PathLike[str]) – Exact output path to inspect.

  • data_class (type | None) – Optional data class used to validate existing content.

Return type:

str | None

Returns:

A message when valid output exists, otherwise None.

qdk_chemistry.ui.io.check_output_exists(filename, data_class=None)[source]

Check if an output file already exists with valid content.

Parameters:

  • filename (str) – The output filename to check

  • data_class (type | None) – Optional data class to validate file content. If provided, attempts to load the file to verify it contains valid data.

Returns:

A message if the file exists with valid content, None otherwise

Return type:

str | None

qdk_chemistry.ui.io.load_data_object(filename, data_class)[source]

Load a data object from either json or hdf5 file based on extension.

Parameters:

  • filename (str | PathLike[str]) – Path to a file with extension (.json or .hdf5/.h5).

  • data_class – The qdk_chemistry.data class to instantiate

Returns:

The loaded data object

Raises:

ValueError – If file extension is not supported

qdk_chemistry.ui.io.save_data_object(data_obj, filename)[source]

Save a data object to either json or hdf5 file based on extension.

Parameters:

  • data_obj – The qdk_chemistry data object to save

  • filename (str | PathLike[str]) – Path to a file with extension (.json or .hdf5/.h5).

Returns:

The filename where data was saved

Return type:

str

Raises:

ValueError – If file extension is not supported