Files

dapi.files.get_ds_path_uri(t, path, verify_exists=False)[source]

Translate DesignSafe-style paths to Tapis URIs.

Converts commonly used DesignSafe path formats (e.g., /MyData/folder, /projects/PRJ-XXXX/folder) to their corresponding Tapis system URIs. Supports MyData, CommunityData, and project-specific paths with automatic system discovery for projects.

Parameters:

  • t (Tapis) – Authenticated Tapis client instance.

  • path (str) – The DesignSafe-style path string to translate. Supported formats: - MyData paths: “/MyData/folder”, “jupyter/MyData/folder” - Community paths: “/CommunityData/folder” - Project paths: “/projects/PRJ-XXXX/folder” - Direct Tapis URIs: “tapis://system-id/path”

  • verify_exists (bool, optional) – If True, verifies the translated path exists on the target Tapis system. Defaults to False.

Returns:

The corresponding Tapis URI (e.g., “tapis://system-id/path”).

Return type:

str

Raises:

  • FileOperationError – If path translation fails, project system lookup fails, or path verification fails (when verify_exists=True).

  • AuthenticationError – If username is required for MyData paths but t.username is not available.

  • ValueError – If the input path format is unrecognized, empty, or incomplete.

Example

>>> uri = get_ds_path_uri(client, "/MyData/analysis/results")
Translated '/MyData/analysis/results' to 'tapis://designsafe.storage.default/username/analysis/results' using t.username

>>> uri = get_ds_path_uri(client, "/projects/PRJ-1234/data", verify_exists=True)
Searching Tapis systems for project ID 'PRJ-1234'...
Found unique matching system: project-1234-abcd-ef01-2345-6789abcdef01
Verifying existence of translated path: tapis://project-1234-abcd-ef01-2345-6789abcdef01/data
Verification successful: Path exists.
dapi.files.tapis_uri_to_local_path(tapis_uri)[source]

Convert a Tapis URI to the corresponding DesignSafe local path.

Converts Tapis system URIs back to their equivalent DesignSafe local paths that would be accessible in a Jupyter environment. This is the reverse operation of get_ds_path_uri().

Parameters:

tapis_uri (str) – The Tapis URI to convert. Supported formats: - “tapis://designsafe.storage.default/username/path” -> “/home/jupyter/MyData/path” - “tapis://designsafe.storage.community/path” -> “/home/jupyter/CommunityData/path” - “tapis://project-*/path” -> “/home/jupyter/MyProjects/path”

Returns:

The corresponding DesignSafe local path, or the original URI if

it’s not a recognized Tapis URI format.

Return type:

str

Raises:

ValueError – If the Tapis URI format is invalid.

Example

>>> local_path = tapis_uri_to_local_path(
...     "tapis://designsafe.storage.default/user/data/file.txt"
... )
>>> print(local_path)  # "/home/jupyter/MyData/data/file.txt"

>>> local_path = tapis_uri_to_local_path(
...     "tapis://designsafe.storage.community/datasets/earthquake.csv"
... )
>>> print(local_path)  # "/home/jupyter/CommunityData/datasets/earthquake.csv"
dapi.files.upload_file(t, local_path, remote_uri)[source]

Upload a local file to a Tapis storage system.

Parameters:

  • t (Tapis) – Authenticated Tapis client instance.

  • local_path (str) – Path to the local file to upload.

  • remote_uri (str) – Tapis URI destination (e.g., “tapis://system/path/file.txt”).

Raises:

  • FileNotFoundError – If the local file does not exist.

  • ValueError – If local_path is not a file or remote_uri is invalid.

  • FileOperationError – If the Tapis upload operation fails.

Example

>>> upload_file(client, "/local/data.txt", "tapis://mysystem/uploads/data.txt")
Uploading '/local/data.txt' to system 'mysystem' at path 'uploads/data.txt'...
Upload complete.
dapi.files.download_file(t, remote_uri, local_path)[source]

Download a file from a Tapis storage system to local filesystem.

Parameters:

  • t (Tapis) – Authenticated Tapis client instance.

  • remote_uri (str) – Tapis URI of the file to download (e.g., “tapis://system/path/file.txt”).

  • local_path (str) – Local filesystem path where the file should be saved.

Raises:

  • ValueError – If local_path is a directory or remote_uri is invalid.

  • FileOperationError – If the download operation fails or remote file not found.

Example

>>> download_file(
...     client, "tapis://mysystem/data/results.txt", "/local/results.txt"
... )
Downloading from system 'mysystem' path 'data/results.txt' to '/local/results.txt'...
Download complete.
dapi.files.list_files(t, remote_uri, limit=100, offset=0)[source]

List files and directories in a Tapis storage system path.

Parameters:

  • t (Tapis) – Authenticated Tapis client instance.

  • remote_uri (str) – Tapis URI of the directory to list (e.g., “tapis://system/path/”).

  • limit (int, optional) – Maximum number of items to return. Defaults to 100.

  • offset (int, optional) – Number of items to skip (for pagination). Defaults to 0.

Returns:

List of file and directory objects from the specified path. Each object contains metadata like name, size, type, and permissions.

Return type:

List[Tapis]

Raises:

  • ValueError – If remote_uri is invalid.

  • FileOperationError – If the listing operation fails or path not found.

Example

>>> files = list_files(client, "tapis://mysystem/data/")
Listing files in system 'mysystem' at path 'data/'...
Found 5 items.
>>> for file in files:
...     print(f"{file.name} ({file.type})")