Files

from wherobots import Files, FilesDrive

Files(client: BaseClient, region: Region | str | None = None)

The Files surface: hands out drives, defaulting to the configured region.

Parameters

BaseClient

required

The shared API connection.

Region | str | None

default:"None"

Default region for drives; None requires one per drive call.

my_files

Files.my_files: FilesDrive

Your personal file area in the default region (Drive.MY_FILES).

drive()

drive(drive: Drive, region: Region | str | None = None) -> FilesDrive

Return the drive object for drive in region.

Parameters

Drive

required

Which drive, e.g. Drive.MY_FILES.

Region | str | None

default:"None"

Region override; defaults to the configured region.

Returns

FilesDrive

The same FilesDrive for the same drive and region on every call.

Raises

WherobotsConfigError: If no region is passed or configured.

FilesDrive

FilesDrive(client: BaseClient, drive: Drive, region: str)

One Files drive in one region: list, create folders, transfer, rename, delete. Obtain one from Files.drive or Files.my_files; do not build it directly.

Parameters

BaseClient

required

The shared API connection.

Drive

required

Which drive this is.

str

required

The region’s public name (e.g. "aws-us-west-2").

drive

FilesDrive.drive: Drive

The drive this object addresses.

region

FilesDrive.region: str

The region this drive lives in.

storage_id

FilesDrive.storage_id: str

The API storage id this drive resolves to.

delete_directory()

delete_directory(path: str) -> None

Delete a folder and everything in it.

Parameters

str

required

Folder path inside the drive (not the root).

delete_file()

delete_file(path: str) -> None

Delete exactly one file.

Parameters

str

required

File path inside the drive.

download_file()

download_file(path: str, local_path: str | os.PathLike[str]) -> Path

Download one file from the drive.

Parameters

str

required

File path inside the drive.

str | os.PathLike[str]

required

Where to write it. An existing folder receives the file under its drive name.

Returns

Path

The local file written.

Raises

WherobotsValidationError: If the folder local_path names does not exist.
WherobotsFileNotFoundError: If the drive has no file at path.
WherobotsS3Error: If the transfer from storage or the local write fails.

list_directory()

list_directory(path: str = '') -> list[FileEntry]

List a folder, following the cursor through every page.

Parameters

str

default:"''"

Folder path inside the drive; "" (the default) is the root.

Returns

list[FileEntry]

Every file and folder directly inside path.

make_directory()

make_directory(path: str) -> None

Create a folder and every missing folder above it, one level at a time. Each level is created explicitly so it is a real folder that stays writable from a notebook. If a level fails, the ones above it stay.

Parameters

str

required

Folder path inside the drive, e.g. "a/b/c".

rename_file()

rename_file(path: str, new_name: str) -> None

Rename a file in place.

Parameters

str

required

Current file path inside the drive.

str

required

The new name — one path segment, not a path.

upload_file()

upload_file(local_path: str | os.PathLike[str], path: str) -> str

Upload one local file to path in the drive.

Parameters

str | os.PathLike[str]

required

The file to send.

str

required

Destination file path inside the drive, e.g. "data/a.csv".

Returns

str

The storage location the file was written to.

Raises

WherobotsValidationError: If the local file is missing or over 500 MiB, or path is not a valid file path.
WherobotsS3Error: If the transfer to storage fails, storage answers other than 2xx (redirects are not followed), or the file cannot be read.

FilesAPI

Import from wherobots.api.files.

FilesAPI(client: BaseClient)

Upload files to Wherobots-managed storage and Storage Integrations. Each upload session fetches short-lived AWS STS credentials scoped to a specific s3:// destination path via POST /storage/credentials. The credentials are wrapped in botocore.credentials.RefreshableCredentials so multi-hour multipart uploads survive the standard 1-hour STS lifetime.

Parameters

BaseClient

required

A configured BaseClient instance.

close()

close() -> None

Close the underlying HTTP client and release resources.

dest_uri_for()

dest_uri_for(
    source: StorageIntegration,
    filename: str,
    subdir: str | None = None,
) -> str

Build an s3:// destination URI under source’s root. Honors source’s default_directory if set, then the optional subdir, then filename. Use the resulting URI with upload_file when you want explicit, predictable destinations (e.g. for a job script you intend to reference as WherobotsJob(script=<uri>)).

Parameters

StorageIntegration

required

A StorageIntegration returned from list_integrations, resolve_integration, or get_managed_storage.

str

required

Bare filename (no slashes).

str | None

default:"None"

Optional path segment(s) between the source root and the filename. Validated against the same traversal rules as filenames.

Returns

str

s3://<bucket>/<...>/<filename>.

Raises

WherobotsValidationError: On filename / subdir traversal.

from_config()

FilesAPI.from_config(config: WherobotsConfig, **kwargs: Any) -> FilesAPI

Build a FilesAPI from a WherobotsConfig.

Parameters

WherobotsConfig

required

Validated configuration object.

Any

Additional keyword arguments forwarded to BaseClient.__init__ (e.g. max_retries).

Returns

FilesAPI

A new FilesAPI instance backed by the configured client.

get_managed_storage()

get_managed_storage(*, refresh: bool = False) -> StorageIntegration

Return the org’s managed storage source. Looks for the entry in GET /storage with type == "MANAGED". Cached on the instance after the first call.

Parameters

bool

default:"False"

Force a fresh fetch.

Returns

StorageIntegration

The managed StorageIntegration.

Raises

WherobotsValidationError: If no managed source is configured.
WherobotsAPIError: On HTTP failures.

get_storage_credentials()

get_storage_credentials(
    path: str,
    access_mode: Literal['read', 'read_write'] = 'read',
) -> TemporaryAwsCredentials

Fetch temporary AWS STS credentials scoped to path. Calls POST /storage/credentials. The server resolves the path against managed storage, the WherobotsDB releases bucket, and any matching Storage Integration in that order.

Parameters

str

required

s3://bucket/prefix URI to obtain credentials for.

Literal['read', 'read_write']

default:"'read'"

"read" (default — least privilege) or "read_write" to also allow s3:PutObject. The SDK’s upload paths pass "read_write" explicitly; callers using this method directly should leave the default unless they specifically need write access.

Returns

TemporaryAwsCredentials

A TemporaryAwsCredentials object — secrets are masked in repr.

Raises

WherobotsAPIError: On HTTP or JSON-parsing failures. The error message and attached payload are scrubbed — neither will reference any credential field even if the server replied with a partially-populated body.

list_integrations()

list_integrations(*, refresh: bool = False) -> list[StorageIntegration]

List all storage sources (GET /storage). Includes the org’s managed source (type == "MANAGED") and any user-configured integration sources (type == "INTEGRATION").

Parameters

bool

default:"False"

Force a fresh fetch even if the instance has cached results.

Returns

list[StorageIntegration]

A list of StorageIntegration objects.

Raises

WherobotsAPIError: On HTTP or JSON-parsing failures.

resolve_integration()

resolve_integration(name_or_id: str, *, refresh: bool = False) -> StorageIntegration

Find a storage integration by name (case-insensitive) or ID.

Parameters

str

required

The integration name or unique ID.

bool

default:"False"

Force a fresh fetch of integrations.

Returns

StorageIntegration

The matching StorageIntegration.

Raises

WherobotsValidationError: If no matching integration is found.
WherobotsAPIError: On HTTP failures.

upload_dependency()

upload_dependency(
    local_path: str,
    *,
    storage_integration: str | None = None,
    dest_filename: str | None = None,
    dest_subdir: str | None = None,
) -> str

Upload a dependency file (wheel, jar, zip, json). Destination rules differ by scope (intentional — the integration owner controls their bucket structure):

Managed (storage_integration=None): file lands under {managed.path}/dependencies/{filename} unless dest_subdir is set, in which case dest_subdir replaces the default dependencies/ segment.
Storage Integration: file lands at {integration.path}/{default_directory}/{dest_subdir}/{filename} (skipping any empty segment). There is no implicit dependencies/ for integrations — if the integration has no default_directory and no dest_subdir is supplied, the file lands at the integration root. Use dest_subdir to organize artifacts inside the integration.

Parameters

str

required

Local file path to upload.

str | None

default:"None"

Optional integration name or ID. When None, the file is uploaded to managed storage.

str | None

default:"None"

Optional destination filename. Defaults to Path(local_path).name.

str | None

default:"None"

Optional subdirectory under the destination source’s root. See destination rules above. Each segment is validated against _validate_filename so traversal is rejected.

Returns

str

The s3:// URI of the uploaded dependency.

Raises

WherobotsValidationError: If the file path, filename, or subdir are invalid, or the storage integration is unknown.
WherobotsAPIError: On credential or upload failures.

upload_file()

upload_file(local_path: str, dest_uri: str) -> str

Upload a local file to an explicit s3:// destination. Fetches read_write credentials scoped to dest_uri, then runs a boto3 multipart upload. Streams from disk — large files are not loaded fully into memory. Credentials are wrapped in a RefreshableCredentials so uploads exceeding the 1h STS lifetime keep working.

Parameters

str

required

Filesystem path to the file to upload.

str

required

Destination s3://bucket/key URI. The server picks the backing bucket from this path.

Returns

str

dest_uri on success.

Raises

WherobotsValidationError: If the local file doesn’t exist or the URI is malformed.
WherobotsAPIError: On credential fetch failure.

upload_managed_file()

upload_managed_file(
    local_path: str,
    subdir: str,
    dest_filename: str | None = None,
) -> str

Upload to managed storage under {managed.path}/{subdir}/{name}.

Parameters

str

required

Local file to upload.

str

required

Subdirectory under the managed source’s path (e.g. "scripts", "dependencies").

str | None

default:"None"

Optional destination filename. Defaults to Path(local_path).name.

Returns

str

The s3:// URI of the uploaded file.

Raises

WherobotsValidationError: If the file path or filename are invalid, or no managed storage is configured.
WherobotsAPIError: On credential or upload failures.

upload_script()

upload_script(content: str | bytes, filename: str | None = None) -> str

Upload script content (string or bytes) to managed storage. Writes content to a temporary file, then delegates to upload_managed_file under the scripts/ subdir. For an already-on-disk file, prefer upload_managed_file directly to avoid the temp-file roundtrip.

Parameters

str | bytes

required

Script source (string) or raw bytes.

str | None

default:"None"

Optional destination filename. Defaults to a UUID-based name (sdk-upload-{uuid}.py).

Returns

str

The s3:// URI of the uploaded script.

Raises

WherobotsValidationError: If the filename is invalid.
WherobotsAPIError: On credential or upload failures.

​Files

​Parameters

​my_files

​drive()

​Parameters

​Returns

​Raises

​FilesDrive

​Parameters

​drive

​region

​storage_id

​delete_directory()

​Parameters

​delete_file()

​Parameters

​download_file()

​Parameters

​Returns

​Raises

​list_directory()

​Parameters

​Returns

​make_directory()

​Parameters

​rename_file()

​Parameters

​upload_file()

​Parameters

​Returns

​Raises

​FilesAPI

​Parameters

​close()

​dest_uri_for()

​Parameters

​Returns

​Raises

​from_config()

​Parameters

​Returns

​get_managed_storage()

​Parameters

​Returns

​Raises

​get_storage_credentials()

​Parameters

​Returns

​Raises

​list_integrations()

​Parameters

​Returns

​Raises

​resolve_integration()

​Parameters

​Returns

​Raises

​upload_dependency()

​Parameters

​Returns

​Raises

​upload_file()

​Parameters

​Returns

​Raises

​upload_managed_file()

​Parameters

​Returns

​Raises

​upload_script()

​Parameters

​Returns

​Raises

Files

Parameters

my_files

drive()

Parameters

Returns

Raises

FilesDrive

Parameters

drive

region

storage_id

delete_directory()

Parameters

delete_file()

Parameters

download_file()

Parameters

Returns

Raises

list_directory()

Parameters

Returns

make_directory()

Parameters

rename_file()

Parameters

upload_file()

Parameters

Returns

Raises

FilesAPI

Parameters

close()

dest_uri_for()

Parameters

Returns

Raises

from_config()

Parameters

Returns

get_managed_storage()

Parameters

Returns

Raises

get_storage_credentials()

Parameters

Returns

Raises

list_integrations()

Parameters

Returns

Raises

resolve_integration()

Parameters

Returns

Raises

upload_dependency()

Parameters

Returns

Raises

upload_file()

Parameters

Returns

Raises

upload_managed_file()

Parameters

Returns

Raises

upload_script()

Parameters

Returns

Raises