File transfer - Nebius Token Factory documentation

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 AsyncClientFileTransfer`

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

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

Attributes

Callable[[TransferProgress], None] | None

Callable[[TransferProgress], None] | None

Methods

`upload()`

async def upload(file) -> FileSpec

required

FileSpec

`read_file()`

async def read_file(image_uuid, path) -> bytes

required

bytes

`iter_file()`

async def iter_file(image_uuid, path) -> AsyncGenerator[bytes, None]

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

required

AsyncGenerator[bytes, None]

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

`download_file()`

async def download_file(image_uuid, path, destination) -> int

Atomically save streamed content.

required

int

The number of downloaded bytes.

`prepare_files()`

async def prepare_files(files) -> dict[str, FileSpec] | None

required

dict[str, FileSpec] | None

`read_stdin()`

async def read_stdin(source) -> str | bytes

required

str | bytes

`class AsyncFileTransfer`

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.

Attributes

Callable[[TransferProgress], None] | None

Callable[[TransferProgress], None] | None

Methods

`upload()`

def upload(file) -> FileSpec

required

FileSpec

`read_file()`

def read_file(image_uuid, path) -> bytes

required

bytes

`prepare_files()`

async def prepare_files(files) -> dict[str, FileSpec] | None

required

dict[str, FileSpec] | None

`iter_file()`

async def iter_file(image_uuid, path) -> AsyncGenerator[bytes, None]

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

required

AsyncGenerator[bytes, None]

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

`download_file()`

async def download_file(image_uuid, path, destination) -> int

Atomically save streamed content.

required

int

The number of downloaded bytes.

`read_stdin()`

async def read_stdin(source) -> str | bytes

required

str | bytes

`class AsyncReadable`

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

Methods

`read()`

async def read(size, /) -> TypeVar(DataT_co, str, bytes, covariant=True)

default:"-1"

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

`class ClientFileTransfer`

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

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

Attributes

Callable[[TransferProgress], None] | None

Callable[[TransferProgress], None] | None

Methods

`upload()`

def upload(file) -> FileSpec

required

FileSpec

`read_file()`

def read_file(image_uuid, path) -> bytes

required

bytes

`iter_file()`

def iter_file(image_uuid, path) -> Generator[bytes, None, None]

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

required

Generator[bytes, None, None]

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

`download_file()`

def download_file(image_uuid, path, destination) -> int

Atomically save streamed content.

required

int

The number of downloaded bytes.

`prepare_files()`

def prepare_files(files) -> dict[str, FileSpec] | None

required

dict[str, FileSpec] | None

`read_stdin()`

def read_stdin(source) -> str | bytes

required

str | bytes

`class Readable`

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

Methods

`read()`

def read(size, /) -> TypeVar(DataT_co, str, bytes, covariant=True)

default:"-1"

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

`class StagedFile`

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

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

Attributes

str

int | None

Methods

`from_spec()`

@classmethod
def from_spec(path, spec) -> StagedFile

Copy a transport attachment, preserving omitted permission fields.

required

StagedFile

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

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

`as_spec()`

def as_spec() -> FileSpec

Create a transport attachment without reading or uploading its source.

FileSpec

A new FileSpec with the recorded metadata.

`class SyncFileTransfer`

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.

Attributes

Callable[[TransferProgress], None] | None

Callable[[TransferProgress], None] | None

Methods

`upload()`

@abstractmethod
def upload(file) -> FileSpec

required

FileSpec

`read_file()`

@abstractmethod
def read_file(image_uuid, path) -> bytes

required

bytes

`prepare_files()`

def prepare_files(files) -> dict[str, FileSpec] | None

required

dict[str, FileSpec] | None

`iter_file()`

def iter_file(image_uuid, path) -> Generator[bytes, None, None]

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

required

Generator[bytes, None, None]

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

`download_file()`

def download_file(image_uuid, path, destination) -> int

Atomically save streamed content.

required

int

The number of downloaded bytes.

`read_stdin()`

def read_stdin(source) -> str | bytes

required

str | bytes

`class TransferProgress`

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

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

Attributes

int | None

Literal['upload', 'download']

Literal[‘upload’, ‘download’]

str

int

`class UploadFileSpec`

class contree_sdk.files.UploadFileSpec(*, uid, gid, mode, path, source)

Attributes

int

PurePosixPath | str | None

int

str | Path | bytes | UploadedFile

str | Path | bytes | UploadedFile

Methods

`prepare_files()`

@classmethod
def prepare_files(files, default_image_path) -> list[UploadFileSpec]

required

default:"'/'"

list[UploadFileSpec]

list[UploadFileSpec]

`class UploadedFile`

class contree_sdk.files.UploadedFile(uuid, sha256)

Attributes

str

`prepare_file_tree()`

def contree_sdk.files.prepare_file_tree(source, destination, *, exclude, uid, gid, mode) -> list[UploadFileSpec]

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.

required

default:"'/'"

default:"()"

default:"0"

default:"None"

list[UploadFileSpec]

list[UploadFileSpec]Prepared attachments in relative-path order.

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

`write_download()`

def contree_sdk.files.write_download(chunks, destination, *, path, on_progress) -> int

Write streamed bytes atomically; preserve the destination on failure.

required

default:"''"

default:"None"

int

The number of downloaded bytes.

`write_download_async()`

async def contree_sdk.files.write_download_async(chunks, destination, *, path, on_progress) -> int

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

required

default:"''"

default:"None"

int

The number of downloaded bytes.

​class AsyncClientFileTransfer

​Attributes

​Methods

​upload()

​read_file()

​iter_file()

​download_file()

​prepare_files()

​read_stdin()

​class AsyncFileTransfer

​Attributes

​Methods

​upload()

​read_file()

​prepare_files()

​iter_file()

​download_file()

​read_stdin()

​class AsyncReadable

​Methods

​read()

​class ClientFileTransfer

​Attributes

​Methods

​upload()

​read_file()

​iter_file()

​download_file()

​prepare_files()

​read_stdin()

​class Readable

​Methods

​read()

​class StagedFile

​Attributes

​Methods

​from_spec()

​as_spec()

​class SyncFileTransfer

​Attributes

​Methods

​upload()

​read_file()

​prepare_files()

​iter_file()

​download_file()

​read_stdin()

​class TransferProgress

​Attributes

​class UploadFileSpec

​Attributes

​Methods

​prepare_files()

​class UploadedFile

​Attributes

​prepare_file_tree()

​write_download()

​write_download_async()

`class AsyncClientFileTransfer`

Attributes

Methods

`upload()`

`read_file()`

`iter_file()`

`download_file()`

`prepare_files()`

`read_stdin()`

`class AsyncFileTransfer`

Attributes

Methods

`upload()`

`read_file()`

`prepare_files()`

`iter_file()`

`download_file()`

`read_stdin()`

`class AsyncReadable`

Methods

`read()`

`class ClientFileTransfer`

Attributes

Methods

`upload()`

`read_file()`

`iter_file()`

`download_file()`

`prepare_files()`

`read_stdin()`

`class Readable`

Methods

`read()`

`class StagedFile`

Attributes

Methods

`from_spec()`

`as_spec()`

`class SyncFileTransfer`

Attributes

Methods

`upload()`

`read_file()`

`prepare_files()`

`iter_file()`

`download_file()`

`read_stdin()`

`class TransferProgress`

Attributes

`class UploadFileSpec`

Attributes

Methods

`prepare_files()`

`class UploadedFile`

Attributes

`prepare_file_tree()`

`write_download()`

`write_download_async()`