utils

Utilities and helper scripts.

Functions

assert_path_exists(path)	Assert that a given path exists.
cache_path(path)	Copy a file or directory to the cache and return the cache path.
enforce_extension(path, extension)	Set the file extension of the given path.
find(name[, environment, guesses])	Finds a particular binary on this system.
get_or_create_directory(path)	Get the given directory, creating it if it doesn't already exist.
get_or_create_file(path)	Get the given file, creating it if it doesn't already exist.
hash(data)	Compute the cryptographic hash of the given bytes.
subprocess([function, timeout])	A decorator that runs the given function in a subprocess.
timestamp([time])	Generate a timestamp string in the standard format.
write_parquet(frame, path, **kwargs)	Write parquet to the given path.

Exceptions

RemoteException(type, representation, traceback)

A wrapper around an exception raised by a remote process.

undertale.utils.timestamp(time: datetime | None = None) → str

Generate a timestamp string in the standard format.

Parameters:

time – An optional datetime for which to generate a timestamp. If not provided the current date and time will be used.

Returns:

A string timestamp in the standard format.

undertale.utils.assert_path_exists(path: str) → str

Assert that a given path exists.

Parameters:

path – The path to check.

Returns:

The absolute version of the given path.

Raises:

PathDoesNotExist – If the given path does not exist.

undertale.utils.cache_path(path: str) → str

Copy a file or directory to the cache and return the cache path.

Checks the UNDERTALE_CACHE environment variable. If set, copies path to $UNDERTALE_CACHE/{md5(dirname(path))[:8]}-{basename(path)}, logging each file copied. The 8-character MD5 hex prefix of the parent directory prevents basename collisions between paths that share the same leaf name. If the destination already exists, verifies each file’s size and modification time (similar to rsync) and re-copies stale files. If UNDERTALE_CACHE is not set, logs a warning and returns the original path unchanged.

Parameters:

path – Path to the file or directory to cache.

Returns:

The cache path if UNDERTALE_CACHE is set, otherwise path.

undertale.utils.get_or_create_file(path: str) → Tuple[str, bool]

Get the given file, creating it if it doesn’t already exist.

Parameters:

path – The path to the file to get or create.

Returns:

The absolute version of the given path and a boolean indicating if it was created by this function.

undertale.utils.get_or_create_directory(path: str) → Tuple[str, bool]

Get the given directory, creating it if it doesn’t already exist.

Parameters:

path – The path to the directory to get or create.

Returns:

The absolute version of the given path and a boolean indicating if it was created by this function.

undertale.utils.find(name: str, environment: str | None = None, guesses: Iterable[str] | None = None) → str

Finds a particular binary on this system.

Attempts to find the binary given by name, first checking the value of the environment variable named environment (if provided), then by checking the system path, then finally checking hardcoded paths in guesses (if provided). This function is cross-platform compatible - it works on Windows, Linux, and Mac. If there are spaces in the path found, this function will wrap its return value in double quotes.

Parameters:

• name – Binary name.

• environment – An optional environment variable to check.

• guesses – An optional list of hardcoded paths to check.

Returns:

A string with the absolute path to the binary if found, otherwise None.

undertale.utils.write_parquet(frame, path: str, **kwargs) → None

Write parquet to the given path.

This helper method enforces some defaults on a typical frame.to_parquet() operation.

Parameters:

• frame – A DataFrame-like object to write (e.g., pandas.DataFrame, polars.DataFrame, etc.)

• path – The path where the parquet file should be written.

• **kargs – Additional kwargs to pass to the underlying to_parquet method, or override from defaults.

Raises:

• ValueError – If the given frame object does not support

• .to_parquet()` –

undertale.utils.subprocess(function: Callable | None = None, timeout: float | None = None) → Callable

A decorator that runs the given function in a subprocess.

Parameters:

timeout – A timeout (seconds) after which to raise an exception. If None, then the subprocess will be allowed to run indefinitely.

Raises:

• TimeoutError – If timeout seconds have passed and function has not returned.

• Exception – If an exception is raised by the decorated function.

exception undertale.utils.RemoteException(type: str, representation: str, traceback: str)

Bases: Exception

A wrapper around an exception raised by a remote process.

Modules

datasets

Dataset-relevant utilities.