ReferenceFilesystem
Filesystem

The filesystem sub-client is accessed via client.fs on a SandboxClient instance.

All remote paths must be absolute POSIX paths; relative paths are rejected client-side before any network I/O. File modes serialize as octal strings, e.g. 0o644 becomes "0644".

read

fs.read(path, offset=0, length=None, timeout=None)

Reads one page of bytes from a remote file.

This exposes the server paging contract directly. Use read_bytes, read_text, or iter_bytes for higher-level reads.

  • Example:
result = client.fs.read("/tmp/data.bin", offset=0, length=1024)
print(result.data, result.next_offset, result.eof)

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • offset: int, optional, byte offset to read from.
    • length: int, optional, max bytes to return in this page.
    • timeout: int, optional, client-side request timeout in seconds.

  • Returns: FsReadResult, with data bytes, next_offset, and eof.

  • Raises:

    • ValueError: If the path is not absolute or arguments are invalid.
    • PolyaxonClientException: If the request fails.

write

fs.write(path, data, mode=420, create=True, append=False, timeout=None)

Writes bytes to a remote file in a single request.

Use upload_file for chunked transfers of local files.

  • Example:
result = client.fs.write("/tmp/hello.txt", b"hello\n")
print(result.path, result.bytes_written, result.created)

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • data: str or bytes, the content to write.
    • mode: int, optional, file mode if the file is created,
      • default: 0o644.
    • create: bool, optional, create the file if it does not exist,
      • default: True.
    • append: bool, optional, append instead of overwrite,
      • default: False.
    • timeout: int, optional, client-side request timeout in seconds.

  • Returns: FsWriteResult, with path, bytes_written, and created.

  • Raises:

    • ValueError: If the path is not absolute.
    • PolyaxonClientException: If the request fails.

read_bytes

fs.read_bytes(path, offset=0, length=None, chunk_size=65536, timeout=None)

Reads a remote file into memory as bytes.

This buffers the requested range in memory. Use iter_bytes for large files.

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • offset: int, optional, byte offset to start from.
    • length: int, optional, max bytes to read, default: until EOF.
    • chunk_size: int, optional, bytes per request, default: 64KiB.
    • timeout: int, optional, client-side request timeout in seconds.

  • Returns: bytes

write_bytes

fs.write_bytes(path, data, mode=420, create=True, append=False, timeout=None)

Writes bytes to a remote file. Alias of write.

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • data: str or bytes, the content to write.
    • mode: int, optional, file mode if the file is created,
      • default: 0o644.
    • create: bool, optional, create the file if it does not exist,
      • default: True.
    • append: bool, optional, append instead of overwrite,
      • default: False.
    • timeout: int, optional, client-side request timeout in seconds.

  • Returns: FsWriteResult, with path, bytes_written, and created.

read_text

fs.read_text(path, offset=0, length=None, chunk_size=65536, encoding='utf-8', errors='strict', timeout=None)

Reads a remote file and decodes it as text.

This buffers the requested range in memory. Use read for explicit chunked reads.

  • Example:
print(client.fs.read_text("/tmp/hello.txt"))

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • offset: int, optional, byte offset to start from.
    • length: int, optional, max bytes to read, default: until EOF.
    • chunk_size: int, optional, bytes per request, default: 64KiB.
    • encoding: str, optional, text encoding, default: utf-8.
    • errors: str, optional, decoding error handling, default: strict.
    • timeout: int, optional, client-side request timeout in seconds.

  • Returns: str

write_text

fs.write_text(path, data, mode=420, create=True, append=False, encoding='utf-8', errors='strict', timeout=None)

Encodes a string and writes it to a remote file.

  • Example:
client.fs.write_text("/tmp/hello.txt", "hello\n")

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • data: str, the text to write.
    • mode: int, optional, file mode if the file is created,
      • default: 0o644.
    • create: bool, optional, create the file if it does not exist,
      • default: True.
    • append: bool, optional, append instead of overwrite,
      • default: False.
    • encoding: str, optional, text encoding, default: utf-8.
    • errors: str, optional, encoding error handling, default: strict.
    • timeout: int, optional, client-side request timeout in seconds.

  • Returns: FsWriteResult, with path, bytes_written, and created.

  • Raises:

    • TypeError: If data is not a string.

iter_bytes

fs.iter_bytes(path, offset=0, length=None, chunk_size=65536, timeout=None)

Iterates over a remote file's content in chunks.

This is the lower-memory option for large files.

  • Example:
for chunk in client.fs.iter_bytes("/tmp/data.bin", chunk_size=1024):
    process(chunk)

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • offset: int, optional, byte offset to start from.
    • length: int, optional, max bytes to read, default: until EOF.
    • chunk_size: int, optional, bytes per request, default: 64KiB.
    • timeout: int, optional, client-side request timeout in seconds.

  • Yields: bytes, file content chunks.

  • Raises:

    • ValueError: If the path is not absolute or arguments are invalid.
    • PolyaxonClientException: If the server returns non-advancing offsets.

download_file

fs.download_file(path, local_path, offset=0, length=None, chunk_size=65536, timeout=None, create_parents=True)

Downloads a remote file to a local path.

The local write uses a .part file followed by os.replace, so the local destination is never left partially written. This makes no statement about remote-side atomicity.

  • Example:
client.fs.download_file("/tmp/results.json", "results.json")

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • local_path: str or Path, the local destination.
    • offset: int, optional, remote byte offset to start from.
    • length: int, optional, max bytes to download, default: until EOF.
    • chunk_size: int, optional, bytes per request, default: 64KiB.
    • timeout: int, optional, client-side request timeout in seconds.
    • create_parents: bool, optional, create local parent directories,
      • default: True.

  • Returns: str, the local destination path.

upload_file

fs.upload_file(local_path, path, mode=420, create=True, chunk_size=65536, timeout=None)

Uploads a local file to a remote sandbox path.

Uploads are chunked but not remote-atomic: a mid-upload failure may leave a partial remote file. Concurrent uploads to the same remote path are unsupported. The mode only applies if the remote file is created.

  • Example:
client.fs.upload_file("data.csv", "/tmp/data.csv")

  • Args:

    • local_path: str or Path, the local file to upload.
    • path: str, an absolute POSIX path on the sandbox.
    • mode: int, optional, file mode if the remote file is created,
      • default: 0o644.
    • create: bool, optional, create the remote file if it does not exist, default: True.
    • chunk_size: int, optional, bytes per request, default: 64KiB.
    • timeout: int, optional, client-side request timeout in seconds.

  • Returns: FsWriteResult, with path, bytes_written, and created.

ls

fs.ls(path, recursive=None, max_entries=None)

Lists a remote directory.

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • recursive: bool, optional, list entries recursively.
    • max_entries: int, optional, max entries to return.

  • Returns: V1FsListResult, with path, entries, and truncated.

mkdir

fs.mkdir(path, parents=False, mode=493)

Creates a remote directory.

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • parents: bool, optional, create parent directories as needed,
      • default: False.
    • mode: int, optional, directory mode, default: 0o755.

  • Returns: V1FsPathResult, with the created path.

rm

fs.rm(path, recursive=False)

Removes a remote file or directory.

  • Args:

    • path: str, an absolute POSIX path on the sandbox.
    • recursive: bool, optional, remove directories recursively,
      • default: False.

  • Returns: V1FsPathResult, with the removed path.

stat

fs.stat(path)

Fetches metadata for a remote file or directory.

  • Args:

    • path: str, an absolute POSIX path on the sandbox.

  • Returns: V1FsStatResult, with path, type, size, mtime, mode, uid, gid, symlink_target.

Process
PTY

On this page

readwriteread_byteswrite_bytesread_textwrite_textiter_bytesdownload_fileupload_filelsmkdirrmstat

Actions

Give us feedbackEdit this page on GitHub