Write Files

Write string content directly to sandbox files.

sandbox.files.write(
    path: str,
    content: str,
    overwrite: bool = False,
    encoding: str = "utf-8"
) -> bool

Maximum content size is 4MB. For larger files, use files.upload().

Parameters

pathstringrequired

Absolute path for the file (must start with /). Parent directories are auto-created.

contentstringrequired

String content to write to the file. The content will be encoded using the specified encoding before writing.

overwriteboolean

Overwrite file if it exists. Default: False (raises SandboxFileExistsError if file exists).

encodingstring

Text encoding for encoding content. Default: "utf-8"

Returns

bool

Returns True if the write was successful.

When to Use files.write vs files.upload

Feature	files.write()	files.upload()
Size Limit	4MB	Unlimited (streaming)
Input Type	String (in memory)	File path (streams from disk)
Use Case	Generated content, configs, text	Large files, binary files, archives
Progress Tracking	No	Yes (callback)
Checksum Verification	No	Yes (optional)

Basic Usage

from concave import sandbox

with sandbox() as sbx:
    # Write a simple text file
    sbx.files.write("/tmp/hello.txt", "Hello, World!")
    
    # Write a JSON file
    import json
    data = {"name": "Alice", "age": 30}
    sbx.files.write("/tmp/data.json", json.dumps(data, indent=2))
    
    # Overwrite an existing file
    sbx.files.write("/tmp/output.txt", "New content", overwrite=True)

Advanced Examples

Writing with Different Encodings

# Write a file with latin-1 encoding
sbx.files.write("/tmp/legacy.txt", "Héllo Wörld", encoding="latin-1")

# Write an ASCII file
sbx.files.write("/tmp/ascii.txt", "Simple ASCII", encoding="ascii")

Writing Configuration Files

import yaml
import toml

# Write YAML config
config = {"database": {"host": "localhost", "port": 5432}}
yaml_content = yaml.dump(config)
sbx.files.write("/tmp/config.yaml", yaml_content)

# Write TOML config
toml_content = toml.dumps(config)
sbx.files.write("/tmp/config.toml", toml_content)

# Write .env file
env_vars = "DATABASE_URL=postgres://localhost\nAPI_KEY=secret123"
sbx.files.write("/tmp/.env", env_vars)

Writing Code Files

# Write a Python script
script = """
import sys
print("Hello from generated script!")
print(f"Python version: {sys.version}")
"""
sbx.files.write("/tmp/script.py", script)

# Execute the script
result = sbx.execute("python /tmp/script.py")
print(result.stdout)

Nested Directories

# Parent directories are created automatically
sbx.files.write("/tmp/deep/nested/path/file.txt", "Content")

# Create multiple files in a structure
files = {
    "/tmp/project/src/main.py": "print('main')",
    "/tmp/project/src/utils.py": "def helper(): pass",
    "/tmp/project/tests/test_main.py": "def test_main(): pass",
    "/tmp/project/README.md": "# My Project"
}

for path, content in files.items():
    sbx.files.write(path, content)

Error Handling

from concave import (
    sandbox,
    SandboxFileExistsError,
    SandboxValidationError,
    SandboxInsufficientStorageError
)

with sandbox() as sbx:
    try:
        sbx.files.write("/tmp/data.txt", "Some content")
        print("File written successfully")
    except SandboxFileExistsError as e:
        print(f"File already exists: {e.path}")
        # Retry with overwrite
        sbx.files.write("/tmp/data.txt", "Some content", overwrite=True)
    except SandboxValidationError as e:
        print(f"Validation error: {e}")
    except SandboxInsufficientStorageError as e:
        print(f"Out of storage space: {e}")

Exceptions

SandboxFileExistsError

Raised when the file already exists and overwrite=False.

SandboxValidationError

Raised when the path is not absolute, content exceeds 4MB limit, or encoding is invalid.

SandboxPermissionDeniedError

Raised when the sandbox doesn't have permission to write to the specified path.

SandboxInsufficientStorageError

Raised when the sandbox has run out of storage space.

SandboxNotFoundError

Raised when the sandbox no longer exists.

SandboxTimeoutError

Raised when the write operation times out (typically after 35 seconds).

SandboxFileError

Base exception for other file operation failures.