Skip to content
Leap0 Leap0 Leap0

FilesystemClient

Source: leap0/_sync/filesystem.py

Signature

Section titled “Signature”
FilesystemClient(transport: Transport)

Overview

Section titled “Overview”

List, read, write, move, copy, delete, and search files inside a sandbox.

Text helpers such as :meth:write_file and :meth:read_file provide the most ergonomic default API. Use the *_bytes variants when you need raw binary access or want to avoid text decoding.

Attributes: None.

Methods

Section titled “Methods”

ls

Section titled “ls”
ls(sandbox: SandboxRef, *, path: str, recursive: bool = False, exclude: list[str] | None = None) -> LsResult

List directory entries.

Args: sandbox: Sandbox ID or object. path: Directory path to list. recursive: List recursively. exclude: Glob patterns to exclude.

Returns: object: Result returned by this operation.

stat

Section titled “stat”
stat(sandbox: SandboxRef, *, path: str) -> FileInfo

Get metadata for a single path.

Args: sandbox: Sandbox ID or object. path: Path used by this operation.

Returns: object: Result returned by this operation.

mkdir

Section titled “mkdir”
mkdir(sandbox: SandboxRef, *, path: str, recursive: bool = False, permissions: str | None = None, http_timeout: float | None = None) -> None

Create a directory. Set recursive to create parent directories.

Args: sandbox: Sandbox ID or object. path: Directory path to create. recursive: Create parents as needed. permissions: Octal permission string (e.g. "755"). http_timeout: Optional HTTP request timeout in seconds for this SDK call.

write_bytes

Section titled “write_bytes”
write_bytes(sandbox: SandboxRef, *, path: str, content: bytes, permissions: str | None = None, http_timeout: float | None = None) -> None

Write raw bytes to a single file path.

Args: sandbox: Sandbox ID or object. path: Destination file path. content: Raw file bytes. permissions: Optional octal permission string.

http_timeout: Optional HTTP request timeout in seconds for this SDK call. Example:

sandbox.filesystem.write_bytes(
    path="/workspace/logo.png",
    content=image_bytes,
)

write_file

Section titled “write_file”
write_file(sandbox: SandboxRef, *, path: str, content: str, encoding: str = 'utf-8', permissions: str | None = None, http_timeout: float | None = None) -> None

Write text to a single file path.

Args: sandbox: Sandbox ID or object. path: Destination file path. content: Text content to write. encoding: Text encoding used before upload. permissions: Optional octal permission string.

http_timeout: Optional HTTP request timeout in seconds for this SDK call. Example:

sandbox.filesystem.write_file(
    path="/workspace/app.py",
    content="print('hello')
",
)

write_files_bytes

Section titled “write_files_bytes”
write_files_bytes(sandbox: SandboxRef, *, files: dict[str, bytes], http_timeout: float | None = None) -> None

Write multiple files in a single request.

Args: sandbox: Sandbox ID or object. files: Mapping of file path to raw bytes content.

http_timeout: Optional HTTP request timeout in seconds for this SDK call. Example:

sandbox.filesystem.write_files_bytes(
    files={"/workspace/a.bin": b"a", "/workspace/b.bin": b"b"},
)

write_files

Section titled “write_files”
write_files(sandbox: SandboxRef, *, files: dict[str, str], encoding: str = 'utf-8', http_timeout: float | None = None) -> None

Write multiple text files in a single request.

Args: sandbox: Sandbox ID or object. files: Mapping of file path to text content. encoding: Text encoding used before upload. http_timeout: Optional HTTP request timeout in seconds for this SDK call.

read_bytes

Section titled “read_bytes”
read_bytes(sandbox: SandboxRef, *, path: str, offset: int | None = None, limit: int | None = None, head: int | None = None, tail: int | None = None, http_timeout: float | None = None) -> bytes

Read a single file and return its raw bytes.

Args: sandbox: Sandbox ID or object. path: Path to the file. offset: Byte offset to start from. limit: Maximum bytes to read. head: Return only the first N lines (mutually exclusive with tail). tail: Return only the last N lines (mutually exclusive with head). http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: bytes: File contents as raw bytes.

Example:

content = sandbox.filesystem.read_bytes(path="/workspace/logo.png")
print(content)

read_file

Section titled “read_file”
read_file(sandbox: SandboxRef, *, path: str, offset: int | None = None, limit: int | None = None, head: int | None = None, tail: int | None = None, encoding: str = 'utf-8', http_timeout: float | None = None) -> str

Read a single file and return its content decoded as text.

Args: sandbox: Sandbox ID or object. path: Path used by this operation. offset: Parameter for this operation. limit: Parameter for this operation. head: Parameter for this operation. tail: Parameter for this operation. encoding: Parameter for this operation. http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

read_files_bytes

Section titled “read_files_bytes”
read_files_bytes(sandbox: SandboxRef, *, paths: list[str], http_timeout: float | None = None) -> dict[str, bytes]

Read multiple files and return raw bytes keyed by path.

Args: sandbox: Sandbox ID or object. paths: Parameter for this operation.

Returns: object: Result returned by this operation.

read_files

Section titled “read_files”
read_files(sandbox: SandboxRef, *, paths: list[str], encoding: str = 'utf-8', http_timeout: float | None = None) -> dict[str, str]

Read multiple files and return decoded text keyed by path.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

delete

Section titled “delete”
delete(sandbox: SandboxRef, *, path: str, recursive: bool = False, http_timeout: float | None = None) -> None

Delete a file or directory.

Args: sandbox: Sandbox ID or object. path: Path to delete. recursive: Required when deleting a non-empty directory. http_timeout: Optional HTTP request timeout in seconds for this SDK call.

set_permissions

Section titled “set_permissions”
set_permissions(sandbox: SandboxRef, *, path: str, mode: str | None = None, owner: str | None = None, group: str | None = None, http_timeout: float | None = None) -> None

Set file mode and optionally change owner and group.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

glob

Section titled “glob”
glob(sandbox: SandboxRef, *, path: str, pattern: str, exclude: list[str] | None = None, http_timeout: float | None = None) -> list[str]

Find file paths matching a glob pattern.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: list[str]: Matching file paths.

grep

Section titled “grep”
grep(sandbox: SandboxRef, *, path: str, pattern: str, include: str | None = None, exclude: list[str] | None = None, http_timeout: float | None = None) -> list[SearchMatch]

Search for a text pattern across files in a directory.

Args: sandbox: Sandbox ID or object. path: Base directory to search from. pattern: Text pattern to search for. include: File pattern filter (e.g. "*.py"). exclude: Glob patterns to exclude.

http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: list[SearchMatch]: Matching lines with file and line metadata.

edit_file

Section titled “edit_file”
edit_file(sandbox: SandboxRef, *, path: str, edits: list[FileEdit], http_timeout: float | None = None) -> EditFileResult

Apply one or more find-and-replace edits to a single file.

Returns: EditFileResult: Unified diff and replacement count.

Args: sandbox: Sandbox ID or object. path: Path used by this operation. edits: Parameter for this operation. http_timeout: Optional HTTP request timeout in seconds for this SDK call.

edit_files

Section titled “edit_files”
edit_files(sandbox: SandboxRef, *, paths: list[str], find: str, replace: str = '', http_timeout: float | None = None) -> list[EditResult]

Replace text across multiple files at once.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: list[EditResult]: Per-file edit results.

move

Section titled “move”
move(sandbox: SandboxRef, *, src_path: str, dst_path: str, overwrite: bool = False, http_timeout: float | None = None) -> None

Move or rename a file or directory.

Args: sandbox: Sandbox ID or object. src_path: Parameter for this operation. dst_path: Parameter for this operation. overwrite: Parameter for this operation.

copy

Section titled “copy”
copy(sandbox: SandboxRef, *, src_path: str, dst_path: str, recursive: bool = False, overwrite: bool | None = None, http_timeout: float | None = None) -> None

Copy a file or directory.

Args: sandbox: Sandbox ID or object. src_path: Source path. dst_path: Destination path. recursive: Required when copying a directory. overwrite: Overwrite the destination if it already exists. http_timeout: Optional HTTP request timeout in seconds for this SDK call.

exists

Section titled “exists”
exists(sandbox: SandboxRef, *, path: str, http_timeout: float | None = None) -> bool

Check whether a path exists in the sandbox.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: bool: True when the path exists.

tree

Section titled “tree”
tree(sandbox: SandboxRef, *, path: str, max_depth: int | None = None, exclude: list[str] | None = None, http_timeout: float | None = None) -> TreeResult

Get a recursive directory tree.

Args: sandbox: Sandbox ID or object. path: Root directory path. max_depth: Maximum traversal depth. exclude: Glob patterns to exclude.

http_timeout: Optional HTTP request timeout in seconds for this SDK call. Returns: TreeResult: Recursive directory tree rooted at path.