Files API¶

Use DeepOriginClient().files to list, upload, download, and delete objects in your organization’s file storage.

from deeporigin.platform.client import DeepOriginClient

client = DeepOriginClient()

Example:

keys = client.files.list(remote_path="entities/")

Choosing a method¶

Use this table to pick the right call. The client uses two upload styles (multipart via the platform API vs. signed URLs to object storage) and two download styles (signed URL streaming vs. direct GET through the API).

Listing and metadata¶

Method	Use when
`list(..., metadata=False)`	You only need remote keys (paths) under a prefix — default for scripts and discovery.
`list(..., metadata=True)`	You need Size, ETag, LastModified, etc., from the API for each object.
`stat(remote_path)`	You need headers for a single file (HEAD) without listing a directory.

Uploads¶

Method	Use when
`upload(local, remote)`	One file; body goes through the platform as multipart (`PUT /files/...`). Simple and authenticated like any other API call.
`upload_many(files={local: remote, ...})`	Many files with explicit local→remote paths; each file uploaded in parallel via the same multipart path as `upload`.
`upload_tree(local_path, remote_dir)`	A directory (recursive) or a list of local files; files go to `remote_dir` preserving relative paths. Uses signed URLs and parallel PUTs — better for large trees and heavy parallelism (bytes skip the app server).
`upload_from_url(remote_path, source_url=...)`	The server should fetch a public URL and store the object; bytes never pass through your machine.

Downloads¶

Method	Use when
`download(remote_path, ...)` (default)	One file; default path uses a signed URL and streams to disk — preferred for large files.
`download(..., direct=True)`	One file via GET through the platform API; response body is read into memory — fine for small files or when you want a single hop through the gateway.
`download_many(files=...)`	Many remote paths (dict of remote→local or list of remotes); each worker calls `download` (default signed-URL streaming).
`download_zip(remote_path, ...)`	You want a directory as a single ZIP download.

Deletes¶

Method	Use when
`delete(remote_path)`	Remove one object.
`delete_many(remote_paths=[...])`	Remove many objects in parallel.

Other¶

Method	Use when
`signed_url(remote_path, upload=False/True)`	You need the raw presigned URL yourself (custom client, browser, `curl`, etc.).
`health()` / `version()`	Service checks or debugging.

src.platform.files.Files ¶

Files API wrapper for org file storage (list, upload, download, delete).

For guidance on choosing between upload / upload_many / upload_tree, download / download_many, and related methods, see docs/platform/ref/files.md (section Choosing a method).

Functions¶

delete ¶

delete(
    remote_path: str, *, timeout: float | None = None
) -> None

Delete a file from UFA.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	The remote path of the file to delete.	required
`timeout`	`float \| None`	Request timeout in seconds. If None, uses the client's default timeout.	`None`

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_many ¶

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

Delete multiple files in parallel.

Parameters:

Name	Type	Description	Default
`remote_paths`	`list[str]`	Remote file paths to delete.	required
`skip_errors`	`bool`	If True, don't raise on failures.	`False`
`max_workers`	`int`	Maximum concurrent deletions.	`20`
`timeout`	`float \| None`	Per-request timeout in seconds.	`None`

Raises:

Type	Description
`RuntimeError`	If any deletion fails and `skip_errors` is False.

download ¶

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

Download a remote file to a local path.

By default uses a signed URL and streams the body to disk (good for large files). Set direct=True to use the HTTP GET file endpoint instead (no signed-URL round trip; body is buffered in memory).

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	Remote file path.	required
`local_path`	`str \| Path \| None`	Local path to save to. If None, uses `~/.deeporigin/` (signed-URL mode uses `remote_path` with leading slashes stripped; direct mode uses `remote_path` as given).	`None`
`lazy`	`bool`	If True and the file already exists locally, skip downloading.	`False`
`download_to_dir`	`str \| Path \| None`	Save using the basename of `remote_path` under this directory (ignored if `local_path` is set).	`None`
`direct`	`bool`	If True, download via `GET /files/{org}/{path}` instead of a signed URL.	`False`

Returns:

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

download_many ¶

download_many(
    *,
    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]`	Mapping of remote paths to local paths (or None for default `~/.deeporigin/` layout), or a list of remote paths.	required
`skip_errors`	`bool`	If True, collect failures instead of raising.	`False`
`lazy`	`bool`	If True, skip download when the local file already exists.	`True`
`max_workers`	`int`	Maximum concurrent downloads.	`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.

download_zip ¶

download_zip(
    remote_path: str,
    *,
    local_path: str | Path | None = None,
    download_to_dir: str | Path | None = None
) -> str

Download a remote directory as a ZIP archive.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	The remote directory path to download.	required
`local_path`	`str \| Path \| None`	Where to save the ZIP file locally. If None, a default name is derived from `remote_path`.	`None`
`download_to_dir`	`str \| Path \| None`	If provided and `local_path` is None, save the ZIP into this directory.	`None`

Returns:

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

health ¶

health() -> dict

Check the health of the files service.

Returns:

Type	Description
`dict`	The JSON health-check response.

list ¶

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

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

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

List objects under a remote path.

Automatically handles pagination using continuation tokens.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	Directory path to list from.	required
`metadata`	`bool`	If False (default), return remote keys only. If True, return full file objects from the API (`Key`, `LastModified`, `ETag`, `Size`, etc.).	`False`
`recursive`	`bool`	If True, recursively list files in subdirectories.	`True`
`last_count`	`int \| None`	Pagination hint — last count of objects in the bucket.	`None`
`delimiter`	`str \| None`	Group results by a common prefix (e.g. `"/"`).	`None`
`max_keys`	`int \| None`	Page size (cannot exceed 1000).	`None`
`prefix`	`str \| None`	Path prefix to filter results.	`None`

Returns:

Type	Description
`list[str] \| list[dict]`	Either a list of remote keys or a list of metadata dicts.

signed_url ¶

signed_url(
    remote_path: str, *, upload: bool = False
) -> str

Return a signed URL for uploading or downloading a file.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	The remote file path.	required
`upload`	`bool`	If True, returns a signed URL for uploading (HTTP PUT). If False, returns a signed URL for downloading (HTTP GET). Defaults to False.	`False`

Returns:

Type	Description
`str`	A signed URL string.

Raises:

Type	Description
`ValueError`	If the API response is missing the 'url' field.

stat ¶

stat(remote_path: str) -> dict[str, str]

Return file metadata from a HEAD request (no body download).

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	Remote file path.	required

Returns:

Type	Description
`dict[str, str]`	HTTP response headers (content-type, content-length, etag, etc.).

upload ¶

upload(
    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_from_url ¶

upload_from_url(
    remote_path: str, *, source_url: str
) -> dict

Upload a file from a URL (server-side fetch).

Tells the server to download the file at source_url and store it at remote_path. The file bytes never transit through the client.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	Destination path on the file server.	required
`source_url`	`str`	Public URL the server should fetch the file from.	required

Returns:

Type	Description
`dict`	The JSON response from the API.

upload_many ¶

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

Upload multiple files in parallel via multipart upload.

Parameters:

Name	Type	Description	Default
`files`	`dict[str, str]`	Mapping of local paths to remote paths.	required
`max_workers`	`int`	Maximum concurrent uploads.	`20`

Returns:

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

Raises:

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

upload_tree ¶

upload_tree(
    local_path: str | Path | list[str | Path],
    remote_dir: str,
    *,
    max_workers: int = 20,
    max_retries: int = 3,
    retry_backoff_factor: float = 1.0,
    skip_errors: bool = False
) -> list[str]

Upload a local file, directory tree, or file list under a remote directory.

Uses signed URLs and parallel workers. Directory uploads preserve relative paths under remote_dir.

Accepts either a list of file paths or a single directory path. When a directory is provided, all files inside it are collected recursively and their relative subdirectory structure is preserved under remote_dir.

Parameters:

Name	Type	Description	Default
`local_path`	`str \| Path \| list[str \| Path]`	A local directory, a single file path, or a list of file paths to upload.	required
`remote_dir`	`str`	Remote directory path (e.g. `"/my-data/"`). A trailing `/` is added automatically if missing.	required
`max_workers`	`int`	Maximum number of concurrent uploads. Defaults to 20.	`20`
`max_retries`	`int`	Maximum retry attempts per file on transient failures. Defaults to 3.	`3`
`retry_backoff_factor`	`float`	Multiplier for exponential back-off between retries. Defaults to 1.0.	`1.0`
`skip_errors`	`bool`	If True, don't raise on individual failures. Defaults to False.	`False`

Returns:

Type	Description
`list[str]`	List of remote paths that were successfully uploaded.

Raises:

Type	Description
`RuntimeError`	If any upload fails and `skip_errors` is False.
`ValueError`	If `local_path` is not a file, directory, or list.

version ¶

version() -> dict

Get the version of the files service.

Returns:

Type	Description
`dict`	The JSON version response.