Tools API.¶

The DeepOriginClient can be used to access the tools API using:

from deeporigin.platform.client import DeepOriginClient

client = DeepOriginClient()

Then, the following methods can be used, for example:

files = client.files.list_files_in_dir(remote_path="entities/")

src.platform.files.Files ¶

Files API wrapper.

Provides access to files-related endpoints through the DeepOriginClient.

Functions¶

delete_file ¶

delete_file(remote_path: str) -> None

Delete a file from UFA.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	The remote path of the file to delete.	required

Raises:

Type	Description
`RuntimeError`	If the file deletion failed. Note: The API returns 200 status even if deletion fails, so this method checks the response body for success.

delete_files ¶

delete_files(
    remote_paths: list[str],
    *,
    skip_errors: bool = False,
    max_workers: int = 20
) -> None

Delete multiple files in parallel.

Parameters:

Name	Type	Description	Default
`remote_paths`	`list[str]`	List of remote file paths to delete.	required
`skip_errors`	`bool`	If True, don't raise RuntimeError on failures. Defaults to False.	`False`
`max_workers`	`int`	Maximum number of concurrent deletions. Defaults to 20.	`20`

Raises:

Type	Description
`RuntimeError`	If any deletion fails and skip_errors is False, with details about all failures.

download_file ¶

download_file(
    remote_path: str,
    *,
    local_path: str | Path | None = None,
    lazy: bool = False
) -> str

Download a single file from UFA to ~/.deeporigin/, or some other local path.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	The remote path of the file to download.	required
`local_path`	`str \| Path \| None`	The local path to save the file to. If None, uses ~/.deeporigin/.	`None`
`lazy`	`bool`	If True, and the file exists locally, return the local path without downloading.	`False`

Returns:

Type	Description
`str`	The local path where the file was saved.

download_files ¶

download_files(
    *,
    files: dict[str, str | None] | list[str],
    skip_errors: bool = False,
    lazy: bool = True,
    max_workers: int = 20
) -> list[str]

Download multiple files in parallel.

Parameters:

Name	Type	Description	Default
`files`	`dict[str, str \| None] \| list[str]`	Either a dictionary mapping remote paths to local paths, or a list of remote paths. Format: {remote_path: local_path or None} or [remote_path1, remote_path2, ...]. If a list is provided, local paths default to None (uses default location ~/.deeporigin/).	required
`skip_errors`	`bool`	If True, don't raise RuntimeError on failures. Defaults to False.	`False`
`lazy`	`bool`	If True, skip downloading if file already exists locally. Defaults to True.	`True`
`max_workers`	`int`	Maximum number of concurrent downloads. Defaults to 20.	`20`

Returns:

Type	Description
`list[str]`	List of local paths where files were saved.

Raises:

Type	Description
`RuntimeError`	If any download fails and skip_errors is False, with details about all failures.

list_files_in_dir ¶

list_files_in_dir(
    remote_path: str,
    *,
    recursive: bool = True,
    last_count: int | None = None,
    delimiter: str | None = None,
    max_keys: int | None = None,
    prefix: str | None = None
) -> list[str]

List files in a directory.

Automatically handles pagination using continuation tokens. All pages are fetched and combined into a single list.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	The path to the directory to list files from.	required
`recursive`	`bool`	If True, recursively list files in subdirectories. Defaults to True.	`True`
`last_count`	`int \| None`	Used for pagination - the last count of objects in the bucket. Defaults to None.	`None`
`delimiter`	`str \| None`	Used to group results by a common prefix (e.g., "/"). Defaults to None.	`None`
`max_keys`	`int \| None`	Page size (cannot exceed 1000). Defaults to None.	`None`
`prefix`	`str \| None`	Path prefix to filter results. Defaults to None.	`None`

Returns:

Type	Description
`list[str]`	List of file paths found in the specified directory.

upload_file ¶

upload_file(
    local_path: str | Path, remote_path: str | Path
) -> dict

Upload a single file to UFA.

Parameters:

Name	Type	Description	Default
`local_path`	`str \| Path`	The local path of the file to upload.	required
`remote_path`	`str \| Path`	The remote path where the file will be stored.	required

Returns:

Type	Description
`dict`	Dictionary containing the upload response (e.g., eTag, s3 metadata).

upload_files ¶

upload_files(
    *, files: dict[str, str], max_workers: int = 20
) -> list[dict]

Upload multiple files in parallel.

Parameters:

Name	Type	Description	Default
`files`	`dict[str, str]`	A dictionary mapping local paths to remote paths. Format: {local_path: remote_path}	required

Returns:

Type	Description
`list[dict]`	List of upload response dictionaries.

Raises:

Type	Description
`RuntimeError`	If any upload fails, with details about all failures.