> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> List, upload, download, rename, and delete files in My Files, and upload files to Wherobots Managed Storage and Storage Integrations.

```python theme={"system"}
from wherobots import Files, FilesDrive
```

## Files

```python theme={"system"}
Files(client: BaseClient, region: Region | str | None = None)
```

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

#### Parameters

**client** `BaseClient` *required*

The shared API connection.

**region** `Region | str | None` (default: None)

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

### my\_files

```python theme={"system"}
Files.my_files: FilesDrive
```

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

### drive()

```python theme={"system"}
drive(drive: Drive, region: Region | str | None = None) -> FilesDrive
```

Return the drive object for `drive` in `region`.

#### Parameters

**drive** `Drive` *required*

Which drive, e.g. `Drive.MY_FILES`.

**region** `Region | str | None` (default: None)

Region override; defaults to the configured region.

#### Returns

**return** `FilesDrive`

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

#### Raises

* `WherobotsConfigError`: If no region is passed or configured.

## FilesDrive

```python theme={"system"}
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

**client** `BaseClient` *required*

The shared API connection.

**drive** `Drive` *required*

Which drive this is.

**region** `str` *required*

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

### drive

```python theme={"system"}
FilesDrive.drive: Drive
```

The drive this object addresses.

### region

```python theme={"system"}
FilesDrive.region: str
```

The region this drive lives in.

### storage\_id

```python theme={"system"}
FilesDrive.storage_id: str
```

The API storage id this drive resolves to.

### delete\_directory()

```python theme={"system"}
delete_directory(path: str) -> None
```

Delete a folder and everything in it.

#### Parameters

**path** `str` *required*

Folder path inside the drive (not the root).

### delete\_file()

```python theme={"system"}
delete_file(path: str) -> None
```

Delete exactly one file.

#### Parameters

**path** `str` *required*

File path inside the drive.

### download\_file()

```python theme={"system"}
download_file(path: str, local_path: str | os.PathLike[str]) -> Path
```

Download one file from the drive.

#### Parameters

**path** `str` *required*

File path inside the drive.

**local\_path** `str | os.PathLike[str]` *required*

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

#### Returns

**return** `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()

```python theme={"system"}
list_directory(path: str = '') -> list[FileEntry]
```

List a folder, following the cursor through every page.

#### Parameters

**path** `str` (default: '')

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

#### Returns

**return** `list[FileEntry]`

Every file and folder directly inside `path`.

### make\_directory()

```python theme={"system"}
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

**path** `str` *required*

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

### rename\_file()

```python theme={"system"}
rename_file(path: str, new_name: str) -> None
```

Rename a file in place.

#### Parameters

**path** `str` *required*

Current file path inside the drive.

**new\_name** `str` *required*

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

### upload\_file()

```python theme={"system"}
upload_file(local_path: str | os.PathLike[str], path: str) -> str
```

Upload one local file to `path` in the drive.

#### Parameters

**local\_path** `str | os.PathLike[str]` *required*

The file to send.

**path** `str` *required*

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

#### Returns

**return** `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`.

```python theme={"system"}
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

**client** `BaseClient` *required*

A configured `BaseClient` instance.

### close()

```python theme={"system"}
close() -> None
```

Close the underlying HTTP client and release resources.

### dest\_uri\_for()

```python theme={"system"}
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

**source** `StorageIntegration` *required*

A `StorageIntegration` returned from
`list_integrations`, `resolve_integration`,
or `get_managed_storage`.

**filename** `str` *required*

Bare filename (no slashes).

**subdir** `str | None` (default: None)

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

#### Returns

**return** `str`

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

#### Raises

* `WherobotsValidationError`: On filename / subdir traversal.

### from\_config()

```python theme={"system"}
FilesAPI.from_config(config: WherobotsConfig, **kwargs: Any) -> FilesAPI
```

Build a `FilesAPI` from a `WherobotsConfig`.

#### Parameters

**config** `WherobotsConfig` *required*

Validated configuration object.

**kwargs** `Any`

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

#### Returns

**return** `FilesAPI`

A new `FilesAPI` instance backed by the configured client.

### get\_managed\_storage()

```python theme={"system"}
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

**refresh** `bool` (default: False)

Force a fresh fetch.

#### Returns

**return** `StorageIntegration`

The managed `StorageIntegration`.

#### Raises

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

### get\_storage\_credentials()

```python theme={"system"}
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

**path** `str` *required*

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

**access\_mode** `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

**return** `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()

```python theme={"system"}
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

**refresh** `bool` (default: False)

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

#### Returns

**return** `list[StorageIntegration]`

A list of `StorageIntegration` objects.

#### Raises

* `WherobotsAPIError`: On HTTP or JSON-parsing failures.

### resolve\_integration()

```python theme={"system"}
resolve_integration(name_or_id: str, *, refresh: bool = False) -> StorageIntegration
```

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

#### Parameters

**name\_or\_id** `str` *required*

The integration name or unique ID.

**refresh** `bool` (default: False)

Force a fresh fetch of integrations.

#### Returns

**return** `StorageIntegration`

The matching `StorageIntegration`.

#### Raises

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

### upload\_dependency()

```python theme={"system"}
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

**local\_path** `str` *required*

Local file path to upload.

**storage\_integration** `str | None` (default: None)

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

**dest\_filename** `str | None` (default: None)

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

**dest\_subdir** `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

**return** `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()

```python theme={"system"}
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

**local\_path** `str` *required*

Filesystem path to the file to upload.

**dest\_uri** `str` *required*

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

#### Returns

**return** `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()

```python theme={"system"}
upload_managed_file(
    local_path: str,
    subdir: str,
    dest_filename: str | None = None,
) -> str
```

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

#### Parameters

**local\_path** `str` *required*

Local file to upload.

**subdir** `str` *required*

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

**dest\_filename** `str | None` (default: None)

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

#### Returns

**return** `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()

```python theme={"system"}
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

**content** `str | bytes` *required*

Script source (string) or raw bytes.

**filename** `str | None` (default: None)

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

#### Returns

**return** `str`

The `s3://` URI of the uploaded script.

#### Raises

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.