qdk_chemistry.ui.validation module

Input validation and project management for QDK Chemistry.

qdk_chemistry.ui.validation.class_data_type_name(dataclass_type)

Return a loader’s static wire-format identifier.

Parameters:

dataclass_type (type[DataClass]) – Data class loader that provides data_type_name().

Return type:

str

Returns:

The loader’s validated wire-format identifier.

Raises:

TypeError – If the loader does not provide data_type_name() or the method does not return a non-empty string.

qdk_chemistry.ui.validation.current_project_name()

Return the project currently validated for this execution context.

Return type:

str | None

qdk_chemistry.ui.validation.current_project_dir()

Return the absolute project directory validated for this execution context.

Return type:

Path | None

qdk_chemistry.ui.validation.strip_filename_path(filename)

Return only the filename, accepting both POSIX and Windows separators.

Return type:

str

Parameters:

filename (str | Path)

qdk_chemistry.ui.validation.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.

exception qdk_chemistry.ui.validation.FilenameFormatError

Bases: Exception

Raised when a filename has an invalid format for the expected data type.

qdk_chemistry.ui.validation.resolve_project_path(project_name, projects_dir)

Resolve a single-component project name beneath the projects directory.

Parameters:

• project_name (str) – Name of the project directory.

• projects_dir (str | Path) – Root directory containing projects.

Return type:

tuple[Path | None, str]

Returns:

The resolved project path and an empty error message, or None and an explanation when the path is invalid.

qdk_chemistry.ui.validation.ensure_filename_format(filename, data_type)

Ensure filename contains the correct type marker for the given data type.

Parameters:

• filename (str) – The filename to check/correct

• data_type (str) – The data type name (e.g., “Wavefunction”, “QubitHamiltonian”)

Return type:

str

Returns:

The corrected filename with proper type marker

Raises:

FilenameFormatError – If the data type is unrecognized or the file extension is invalid

qdk_chemistry.ui.validation.validate_project(func)

Decorator to validate project before executing the function.

Validates that a project exists and exposes its absolute directory through the current execution context. The process working directory is unchanged.

It expects the decorated function to have project_name as its first parameter after self (if applicable).

Parameters:

func (TypeVar(F, bound= Callable[..., Any])) – The function to decorate. Must have project_name: str as a parameter.

Returns:

The decorated function with project validation logic, or str: a JSON string with error information.

Return type:

TypeVar(F, bound= Callable[..., Any])

Example:

@validate_project
@app.tool()
def my_function(project_name: str, other_param: int) -> str:
    # This function will only execute if project_name is valid
    return "success"

qdk_chemistry.ui.validation.is_project_valid(project_name, projects_dir)

Checks validity of base project dir/name combination.

Tries to make the directory if it doesn’t exist yet. This function does not change the process working directory.

Parameters:

• project_name (str) – Name of specific project

• projects_dir (str | Path) – Path to all projects directories (can be string or Path)

Return type:

tuple[bool, str]

Returns:

Tuple[bool, str] that states whether the project is valid, and if not, an explanation