CuaCua

Files

Upload, download, list and remove files in a sandbox through cua-spacesd.

Paths are guest paths unless a parameter names a local one. Transfers are chunked, so size is not capped.

Python programs usually use the high-level API instead: sb.files.

File methods#

Methods of SpacesdClient.

SpacesdClient.upload#

Uploads bytes to path (chunked, resumable, SHA-256 verified).

async def upload(self, path: str, data: bytes, options: Optional[UploadOptions]) -> TransferResult
ParameterTypeDefault
pathStringrequired
dataVec<u8>required
optionsOption<UploadOptions>required

Returns TransferResult · Async · Raises CuaError

Example

import asyncio
 
import cua
 
async def main():
    guest = await cua.embedded().spacesd(URL, TOKEN)
    sent = await guest.upload("/tmp/note.txt", b"hi from the host", None)
    back = await guest.download("/tmp/note.txt")
    print([sent.size, back])
    # [16, b'hi from the host']
 
asyncio.run(main())

SpacesdClient.upload_file#

Uploads a local file to path.

async def upload_file(self, local_path: str, path: str, options: Optional[UploadOptions]) -> TransferResult
ParameterTypeDefault
local_pathStringrequired
pathStringrequired
optionsOption<UploadOptions>required

Returns TransferResult · Async · Raises CuaError

SpacesdClient.download#

Downloads path into memory. user reads as that guest user (see UploadOptions.user).

async def download(self, path: str, user: Optional[str] = None) -> bytes
ParameterTypeDefault
pathStringrequired
userOption<String>None

Returns Vec<u8> · Async · Raises CuaError

SpacesdClient.download_file#

Downloads path to a local file. user reads as that guest user.

async def download_file(self, path: str, local_path: str, user: Optional[str] = None) -> TransferResult
ParameterTypeDefault
pathStringrequired
local_pathStringrequired
userOption<String>None

Returns TransferResult · Async · Raises CuaError

SpacesdClient.stat#

Stat. user acts as that guest user (see UploadOptions.user); xattr_namespace picks the extended-attribute prefix reported in FileEntry.metadata (default user.cua.meta.). no_follow reports a symbolic link itself rather than its target.

async def stat(self, path: str, user: Optional[str] = None, xattr_namespace: Optional[str] = None, no_follow: bool = False) -> FileEntry
ParameterTypeDefault
pathStringrequired
userOption<String>None
xattr_namespaceOption<String>None
no_followboolfalse

Returns FileEntry · Async · Raises CuaError

SpacesdClient.list_dir#

ListDir (depth 1 = direct children), as user.

async def list_dir(self, path: str, depth: int, user: Optional[str] = None, xattr_namespace: Optional[str] = None) -> List[FileEntry]
ParameterTypeDefault
pathStringrequired
depthu32required
userOption<String>None
xattr_namespaceOption<String>None

Returns Vec<FileEntry> · Async · Raises CuaError

SpacesdClient.make_dir#

MakeDir (with parents), as user: the new directories are owned by that user.

async def make_dir(self, path: str, user: Optional[str] = None) -> FileEntry
ParameterTypeDefault
pathStringrequired
userOption<String>None

Returns FileEntry · Async · Raises CuaError

SpacesdClient.move_path#

Move: renames source to destination, as user. overwrite replaces an existing destination (otherwise it fails with AlreadyExists); create_parents makes the destination's missing parent directories (owned by user).

async def move_path(self, source: str, destination: str, overwrite: bool = False, create_parents: bool = False, user: Optional[str] = None) -> FileEntry
ParameterTypeDefault
sourceStringrequired
destinationStringrequired
overwriteboolfalse
create_parentsboolfalse
userOption<String>None

Returns FileEntry · Async · Raises CuaError

SpacesdClient.remove#

Remove, as user.

async def remove(self, path: str, recursive: bool, user: Optional[str] = None) -> None
ParameterTypeDefault
pathStringrequired
recursiveboolrequired
userOption<String>None

Async · Raises CuaError

FileEntry record#

A file or directory in the guest.

Returned by SpacesdClient.list_dir, SpacesdClient.make_dir, SpacesdClient.move_path, SpacesdClient.stat.

FieldTypeDefaultDescription
nameStringBase name.
pathStringAbsolute path.
kindStringfile, directory, symlink or other.
sizeu64Size in bytes.
modeu32Unix mode bits.
modified_ms / modifiedMsOption<i64>Modification time (Unix ms), when known.
symlink_target / symlinkTargetOption<String>Symlink target.
ownerOption<String>Owning user name (a numeric id when the guest has no such user); None where the guest has no owners (Windows).
groupOption<String>Owning group name; None where the guest has none (Windows).
metadataHashMap<String, String>Extended attributes under the call's xattr_namespace (default user.cua.meta.), without the prefix. Empty when there are none or the guest file system has no extended attributes.

TransferResult record#

Result of an upload or download.

Returned by SpacesdClient.download_file, SpacesdClient.upload, SpacesdClient.upload_file.

FieldTypeDefaultDescription
sizeu64Bytes transferred.
sha256StringSHA-256 (hex) of the content.
resumesu32Resumes after dropped connections.

UploadOptions record#

Upload options.

FieldTypeDefaultDescription
create_new / createNewboolfalseFail when the file exists (instead of overwriting).
appendboolfalseAppend instead of overwriting.
permissionsu320Unix permissions (0 = default).
create_parents / createParentsbooltrueCreate missing parent directories.
userOption<String>NoneGuest user to write as: the file (and parents it creates) is owned by that user and the user's permissions apply. Needs a guest agent that runs as root or has passwordless sudo (the Linux images do); otherwise the call fails with a permission error that says why.
metadataOption<HashMap<String, String>>NoneExtended attributes to store with the file, published atomically with its content. At most 32 keys; a key is 1-128 bytes of A-Za-z0-9._:/@+-, a value at most 1024 bytes, 3072 bytes in all.
xattr_namespace / xattrNamespaceOption<String>NoneExtended-attribute key prefix for metadata (and for the metadata reported back): must start with user. and end with .. Default user.cua.meta..