File transfer

See Work with sandbox files for upload and download scenarios, and Customize the SDK for transfer implementations. Import file types from contree_sdk.files.

Public file-transfer contracts and client-backed implementations.

class contree_sdk.files.AsyncClientFileTransfer(client, *, max_concurrency=4, on_progress=None)

File transfer using a caller-owned asynchronous contree-client.

max_concurrency = 4

on_progress: Callable[[TransferProgress], None] | None = None

async upload(file)

Return type:

FileSpec

async read_file(image_uuid, path)

Return type:

bytes

async iter_file(image_uuid, path)

Yield file content. Override this buffered fallback for streaming backends.

Yields:

File content chunks. Close the generator if iteration stops early.

Return type:

AsyncGenerator[bytes, None]

async download_file(image_uuid, path, destination)

Atomically save streamed content.

Return type:

int

Returns:

The number of downloaded bytes.

async prepare_files(files)

Return type:

dict[str, FileSpec] | None

async read_stdin(source)

Return type:

str | bytes

class contree_sdk.files.AsyncFileTransfer

Native async counterpart of SyncFileTransfer.

prepare_files limits uploads to max_concurrency workers. It cancels and joins sibling uploads when one fails. Custom backends can replace batching.

max_concurrency = 4

on_progress: Callable[[TransferProgress], None] | None = None

abstractmethod async upload(file)

Return type:

FileSpec

abstractmethod async read_file(image_uuid, path)

Return type:

bytes

async prepare_files(files)

Return type:

dict[str, FileSpec] | None

async iter_file(image_uuid, path)

Yield file content. Override this buffered fallback for streaming backends.

Yields:

File content chunks. Close the generator if iteration stops early.

Return type:

AsyncGenerator[bytes, None]

async download_file(image_uuid, path, destination)

Atomically save streamed content.

Return type:

int

Returns:

The number of downloaded bytes.

async read_stdin(source)

Return type:

str | bytes

class contree_sdk.files.AsyncReadable(*args, **kwargs)

async read(size=-1, /)

Return type:

TypeVar(DataT_co, str, bytes, covariant=True)

class contree_sdk.files.ClientFileTransfer(client, *, max_concurrency=1, on_progress=None)

File transfer using a caller-owned synchronous contree-client.

max_concurrency = 1

on_progress: Callable[[TransferProgress], None] | None = None

upload(file)

Return type:

FileSpec

read_file(image_uuid, path)

Return type:

bytes

iter_file(image_uuid, path)

Yield file content. Override this buffered fallback for streaming backends.

Yields:

File content chunks. Close the generator if iteration stops early.

Return type:

Generator[bytes, None, None]

download_file(image_uuid, path, destination)

Atomically save streamed content.

Return type:

int

Returns:

The number of downloaded bytes.

prepare_files(files)

Return type:

dict[str, FileSpec] | None

read_stdin(source)

Return type:

str | bytes

class contree_sdk.files.Readable(*args, **kwargs)

read(size=-1, /)

Return type:

TypeVar(DataT_co, str, bytes, covariant=True)

class contree_sdk.files.StagedFile(path, uuid, uid=0, gid=0, mode=420)

An uploaded file and its destination metadata, detached from a local source.

path: str

uuid: str

uid: int | None = 0

gid: int | None = 0

mode: int | None = 420

classmethod from_spec(path, spec)

Copy a transport attachment, preserving omitted permission fields.

Return type:

StagedFile

Returns:

A detached attachment with an octal mode converted to an integer.

Raises:

ValueError – The upload UUID is missing or the mode is not octal.

as_spec()

Create a transport attachment without reading or uploading its source.

Return type:

FileSpec

Returns:

A new FileSpec with the recorded metadata.

class contree_sdk.files.SyncFileTransfer

Replace upload, download, or stdin handling without replacing a session.

Returned FileSpec values identify uploads on the same server as the session. Input streams belong to the caller and must not be closed by this component.

max_concurrency = 1

on_progress: Callable[[TransferProgress], None] | None = None

abstractmethod upload(file)

Return type:

FileSpec

abstractmethod read_file(image_uuid, path)

Return type:

bytes

prepare_files(files)

Return type:

dict[str, FileSpec] | None

iter_file(image_uuid, path)

Yield file content. Override this buffered fallback for streaming backends.

Yields:

File content chunks. Close the generator if iteration stops early.

Return type:

Generator[bytes, None, None]

download_file(image_uuid, path, destination)

Atomically save streamed content.

Return type:

int

Returns:

The number of downloaded bytes.

read_stdin(source)

Return type:

str | bytes

class contree_sdk.files.TransferProgress(direction, path, bytes_transferred, total_bytes=None)

Completed upload size or cumulative downloaded bytes for one remote path.

total_bytes: int | None = None

direction: Literal['upload', 'download']

path: str

bytes_transferred: int

class contree_sdk.files.UploadFileSpec(*, uid=0, gid=0, mode=420, path=None, source)

gid: int = 0

mode: int = 420

path: PurePosixPath | str | None = None

classmethod prepare_files(files, default_image_path='/')

Return type:

list[UploadFileSpec]

uid: int = 0

source: str | Path | bytes | UploadedFile

class contree_sdk.files.UploadedFile(uuid, sha256)

uuid: str

sha256: str

contree_sdk.files.prepare_file_tree(source, destination='/', *, exclude=(), uid=0, gid=0, mode=None)

Expand directory contents into regular files in stable relative-path order.

Patterns match POSIX relative paths, or basenames when they contain no slash. Excluded directories are pruned. Symlinks and special files raise ValueError. Empty directories cannot be represented by spawn attachments and are omitted. mode=None preserves permission bits; ownership defaults to uid=gid=0.

Return type:

list[UploadFileSpec]

Returns:

Prepared attachments in relative-path order.

Raises:

ValueError – The source is not a directory, or an included entry is not a regular file or directory.

contree_sdk.files.write_download(chunks, destination, *, path='', on_progress=None)

Write streamed bytes atomically; preserve the destination on failure.

Return type:

int

Returns:

The number of downloaded bytes.

async contree_sdk.files.write_download_async(chunks, destination, *, path='', on_progress=None)

Write streamed bytes atomically, joining local writes before cancellation escapes.

Return type:

int

Returns:

The number of downloaded bytes.