Download Files

Stream files from the sandbox to your local filesystem.

sandbox.download_file(
    remote_path: str,
    local_path: str,
    overwrite: bool = False,
    progress: Optional[callable] = None,
    verify_checksum: bool = False
) -> bool

Parameters

remote_pathstringrequired

Absolute path in the sandbox to download from. Must start with /.

local_pathstringrequired

Path on local filesystem where file should be saved. Can be relative or absolute.

overwriteboolean

Whether to overwrite the local file if it exists. Defaults to False.

progresscallable

Optional callback function to track download progress. Called periodically with bytes received.

def on_progress(received: int) -> None:
    # received: bytes downloaded so far
    pass

verify_checksumboolean

Verify MD5 checksum after download. Defaults to False.

Returns

Returns True on success. Raises SandboxFileExistsError when local file exists.

Examples

Basic Example

from concave import Sandbox, SandboxFileExistsError

sbx = Sandbox.create()

# Generate a file in the sandbox
sbx.run(
    "with open('/tmp/output.txt', 'w') as f: "
    "f.write('Hello World')"
)

# Download the file
try:
    success = sbx.download_file("/tmp/output.txt", "./output.txt")
    print(f"File downloaded: {success}")
    with open("./output.txt", "r") as f:
        print(f"Contents: {f.read()}")
except SandboxFileExistsError:
    print("Local file already exists")
finally:
    sbx.delete()

Download with Progress Tracking

from concave import Sandbox, SandboxFileExistsError

sbx = Sandbox.create()

# Create a large file in the sandbox
sbx.execute("dd if=/dev/urandom of=/tmp/large_file.bin bs=1M count=50")

def on_progress(received: int):
    mb_received = received / (1024 * 1024)
    print(f"\rDownloading: {mb_received:.2f} MB", end="")

success = sbx.download_file(
    "/tmp/large_file.bin",
    "./downloaded.bin",
    progress=on_progress
)
print(f"\nDownload completed: {success}")

sbx.delete()

Download with Checksum Verification

from concave import Sandbox

sbx = Sandbox.create()

# Create a file in the sandbox
sbx.run("open('/tmp/data.txt', 'w').write('Important data')")

# Download with automatic checksum verification
success = sbx.download_file(
    "/tmp/data.txt",
    "./checksum_data.txt",
    verify_checksum=True
)

print("File downloaded and verified successfully")

sbx.delete()

Download Multiple Files

from concave import Sandbox

sbx = Sandbox.create()

sbx.run("open('/tmp/file1.txt', 'w').write('Data 1')")
sbx.run("open('/tmp/file2.txt', 'w').write('Data 2')")

files = [
    ("/tmp/file1.txt", "./file1.txt"),
    ("/tmp/file2.txt", "./file2.txt"),
]

for remote, local in files:
    sbx.download_file(remote, local)
    print(f"Downloaded {remote}")

sbx.delete()

Overwrite Protection

from concave import Sandbox, SandboxFileExistsError

sbx = Sandbox.create()

# Generate a file in sandbox
sbx.run("open('/tmp/data.txt', 'w').write('Remote data')")

# First download succeeds
success = sbx.download_file(
    "/tmp/data.txt",
    "./data.txt"
)
print(f"First download: {success}")  # True

# Second download raises error (file exists)
try:
    sbx.download_file(
        "/tmp/data.txt",
        "./data.txt"
    )
    print("This should not print!")
except SandboxFileExistsError:
    print("Second download raised error as expected")

# Force overwrite
success = sbx.download_file(
    "/tmp/data.txt",
    "./data.txt",
    overwrite=True
)
print(f"Overwrite download: {success}")  # True

sbx.delete()

Exceptions

SandboxFileNotFoundErrorException

Raised when the remote file doesn't exist in the sandbox.

SandboxValidationErrorException

Raised when remote_path is not absolute (doesn't start with /).

SandboxNotFoundErrorException

Raised when the sandbox no longer exists.

SandboxTimeoutErrorException

Raised when download times out.

SandboxFileErrorException

Raised when local file cannot be written (permissions, disk space, etc.) or checksum verification fails.

Error Handling

from concave import (
    Sandbox,
    SandboxFileNotFoundError,
    SandboxFileError,
    SandboxFileExistsError
)

sbx = Sandbox.create()

try:
    success = sbx.download_file(
        "/tmp/data.txt",
        "./output.txt",
        verify_checksum=True
    )
    print(f"Download successful: {success}")
except SandboxFileNotFoundError:
    print("Remote file not found in sandbox")
except SandboxFileExistsError:
    print("Local file already exists")
except SandboxFileError as e:
    print(f"Download error: {e}")
finally:
    sbx.delete()