Python SDK: app file manager

The file manager lives on client.apps.files. Every method takes the app id first, then a path inside the app. Paths are at most 256 characters. Examples use the client from Creating the client. app_id is the id of one of your apps: client.account.me() lists them.

Listing a directory

files.list(app_id, path=None) lists a directory (the app root when path is omitted). Unlike other optional modifiers, path can be passed by position.

for entry in client.apps.files.list(app_id, "/src"):
    print(entry["type"], entry["name"], entry.get("size"), entry.get("lastModified"))

Field	Type	Description
`name`	`str`	Entry name
`type`	`"file" \| "directory"`	Entry kind
`size`	`int`, optional	Size in bytes. Absent on some directory entries
`lastModified`	`float \| None`, optional	Unix ms (may carry a fraction); `None` when unreadable

A directory that does not exist is 404 FILE_NOT_FOUND. A path the file manager does not expose is 403 BLOCKED_PATH.

Reading a file

files.read(app_id, path) returns the file’s content as bytes. Files are limited to 10 MB: a larger one is 413 FILE_TOO_LARGE.

import json

data = client.apps.files.read(app_id, "/config.json")
text = data.decode()

print(json.loads(text))

Writing a file

files.write(app_id, path, content) creates or overwrites a file.

A str is sent as plain text.
bytes are sent as base64, so any binary content round-trips.
Empty content ('' or b'') creates an empty file.

import json
import urllib.request

# Text
client.apps.files.write(app_id, "/config.json", json.dumps({"debug": False}))

# Binary
with urllib.request.urlopen(image_url) as response:
    image = response.read()
client.apps.files.write(app_id, "/assets/logo.png", image)

Content over 10 MB fails locally with FILE_TOO_LARGE (status 0) before anything is sent. Content over 1 MiB is sent without a timeout once connected, like an upload. For larger files, use apps.commit().

Writing does not restart the app. Call apps.restart() to apply the change.

Moving or renaming a file

client.apps.files.move(app_id, "/config.json", "/config.old.json")

Deleting a file

client.apps.files.delete(app_id, "/config.old.json")

Errors

Status	Code	When
0	`FILE_TOO_LARGE`	`write` content over 10 MB (checked locally)
400	`INVALID_PATH`	The path fails validation (traversal, invalid characters, too long), or `move` to the same path
400	`DELETE_FAILED`, `RENAME_FAILED`	The cluster could not delete or rename the file
403	`BLOCKED_PATH`	The path is not exposed by the file manager
403	`PERMISSION_DENIED`	Your workspace role cannot touch a restricted file (such as `.env`)
404	`FILE_NOT_FOUND`	The file or directory does not exist
413	`FILE_TOO_LARGE`	`read` of a file over 10 MB
429	`KEEP_CALM`	More than 10 writes in 5 seconds

See Errors for the codes every call can return.

Next steps

Environment variables

Read and change the variables of an app.

File manager API reference

The REST endpoints behind these methods.

Manage files from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

Python SDK: app file manager

Listing a directory

Reading a file

Writing a file

Moving or renaming a file

Deleting a file

Errors

Next steps

Environment variables

File manager API reference

Manage files from the CLI

​Listing a directory

​Reading a file

​Writing a file

​Moving or renaming a file

​Deleting a file

​Errors

​Next steps

Environment variables

File manager API reference

Manage files from the CLI

Listing a directory

Reading a file

Writing a file

Moving or renaming a file

Deleting a file

Errors

Next steps