zea.datapaths

Utility functions for handling local data paths.

This module provides utilities for managing local and remote data paths in zea projects. It supports user- and machine-specific configuration via a users.yaml file, allowing dynamic resolution of data roots for portable and reproducible workflows.

See the notebook Using Local Data Paths with zea for an extensive example of how to set up your local data paths.

Example usage

from zea.datapaths import set_data_paths

user = set_data_paths("users.yaml")
print(user.data_root)

Functions

create_new_user([user_config_path, local])	Creates a new user profile in users.yaml if one does not already exist.
format_data_path(path[, user])	If the path is not absolute, prepend the data_root to it.
set_data_paths([user_config, local, verify])	Get data paths (absolute paths to location of data).

Exceptions

NoYamlFileError	Raised when the users.yaml file is not found.
UnknownHostnameWarning	Custom Warning indicating that the hostname was not found for this user in the user.yaml file
UnknownLocalRemoteWarning	Custom Warning indicating that the data_root corresponding to the local or remote key was not found in the user.yaml file
UnknownUsernameWarning	Custom Warning indicating that the username was not found in the user.yaml file

exception zea.datapaths.NoYamlFileError

Bases: Warning

Raised when the users.yaml file is not found.

exception zea.datapaths.UnknownHostnameWarning

Bases: UserWarning

Custom Warning indicating that the hostname was not found for this user in the user.yaml file

exception zea.datapaths.UnknownLocalRemoteWarning

Bases: UserWarning

Custom Warning indicating that the data_root corresponding to the local or remote key was not found in the user.yaml file

exception zea.datapaths.UnknownUsernameWarning

Bases: UserWarning

Custom Warning indicating that the username was not found in the user.yaml file

zea.datapaths.create_new_user(user_config_path=None, local=None)

Creates a new user profile in users.yaml if one does not already exist.

Parameters:

• user_config (str) – Path that points to yaml file with user info. Defaults to None. In that case ./users.yaml is taken

• local (bool) – Use local dataset or get from remote (NAS). Per machine, the data_root can be set to a local or remote path. Each user can also have a different data_root for each machine. Default is None, which means that the data_root is shared for either local or remote (i.e. this parameter is ignored), see doc set_data_paths().

zea.datapaths.format_data_path(path, user=None)

If the path is not absolute, prepend the data_root to it.

Return type:

Path

zea.datapaths.set_data_paths(user_config=None, local=True, verify=True)

Get data paths (absolute paths to location of data).

Parameters:

• user_config (str or dict, optional) – Path to a YAML file with user info. If None, uses ./users.yaml as the default file. Can also be a dictionary structured as shown below.

• local (bool, optional) – Use local dataset or get from NAS.

• verify (bool, optional) – Verify that the paths exist and are directories. Default is True.

Example YAML structure:

data_root: ...
output: ...

You can also specify different data_root for different users and machines:

my_username:
  my_hostname:
    system: windows
    data_root: ...
    output: ...
  other_hostname:
    system: linux
    data_root:
      local: ...
      remote: ...
  # If both my_hostname and other_hostname are not matching, fallback to:
  system: linux
  data_root: ...

other_username:
  data_root: ...

These will take precedence over the data_root that is userless and machineless.

Returns:

Absolute paths to location of data. Stores the following parameters:

data_root, zea_root, output, system, username, hostname

Return type:

dict