Sessions

class contree_sdk.sdk.objects.session.ContreeSession(image)

async download(image_path, local_path=None)

Download a file from the image to local filesystem.

Parameters:

• image_path (str | Path) – Path to the file inside the image.

• local_path (str | Path | None) – Local destination path. Defaults to filename from image_path.

Return type:

Path | None

Returns:

Path to the downloaded file.

property elapsed: timedelta

Time elapsed during execution.

property exit_code: int

Exit code of the executed command.

async ls(path='/')

List files and directories at the given path.

Parameters:

path (str | Path) – Path inside the image to list.

Return type:

list[ImageFile | ImageDirectory]

Returns:

List of ImageFile and ImageDirectory objects.

async read(image_path)

Read file contents from the image.

Parameters:

image_path (str | Path) – Path to the file inside the image.

Return type:

bytes

Returns:

File contents as bytes.

property result: ContreeResult

Execution result. Only available after successful execution.

run(command=None, shell=None, args=None, env=None, cwd=None, hostname=None, stdin=None, stdout=None, stderr=None, tag=None, files=None, timeout=None, disposable=True)

Prepare image for command execution.

Parameters:

• command (str | None) – Command to execute (mutually exclusive with shell).

• shell (str | None) – Shell command string (mutually exclusive with command).

• args (Iterable[str] | None) – Command arguments.

• env (dict[str, str] | None) – Environment variables.

• cwd (str | None) – Working directory inside the image.

• hostname (str | None) – Hostname for the container.

• stdin (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Input source.

• stdout (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Output destination for stdout.

• stderr (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Output destination for stderr.

• tag (str | None) – Tag for the resulting image.

• files (list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None) – Files to upload into the image.

• timeout (float | timedelta | None) – Execution timeout in seconds or as timedelta.

• disposable (bool) – If True, image is discarded after execution.

Return type:

Self

Returns:

New image instance configured for execution.

Raises:

DisposableImageRunError – If attempting to run on a disposed image.

property state: ImageState

Current state of the image in the execution lifecycle.

property stderr: str | bytes | Path | IO | Literal[-1] | None

Stderr output from the execution.

property stdin: IO | None

Configured stdin source.

property stdout: str | bytes | Path | IO | Literal[-1] | None

Stdout output from the execution.

uuid: UUID | None

Unique identifier of the image.

tag: str | None

Optional tag associated with the image.

class contree_sdk.sdk.objects.session.ContreeSessionSync(image)

download(image_path, local_path=None)

Download a file from the image to local filesystem.

Parameters:

• image_path (str | Path) – Path to the file inside the image.

• local_path (str | Path | None) – Local destination path. Defaults to filename from image_path.

Return type:

Path | None

Returns:

Path to the downloaded file.

property elapsed: timedelta

Time elapsed during execution.

property exit_code: int

Exit code of the executed command.

ls(path='/')

List files and directories at the given path.

Parameters:

path (str | Path) – Path inside the image to list.

Return type:

list[ImageFileSync | ImageDirectorySync]

Returns:

List of ImageFileSync and ImageDirectorySync objects.

popen(args=None, *, stdin=None, input=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, check=False, text=None, env=None)

Run a command with subprocess-like interface.

Parameters:

• args (list[str] | None) – Command and arguments list.

• stdin (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Input source.

• input (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Alternative input source (alias for stdin).

• stdout (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Output destination for stdout.

• stderr (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Output destination for stderr.

• shell (bool) – If True, treat args as shell command.

• cwd (str | None) – Working directory inside the image.

• timeout (float | None) – Execution timeout in seconds.

• check (bool) – If True, raise on non-zero exit code.

• text (bool | None) – If True, decode output as text.

• env (dict[str, str] | None) – Environment variables.

Return type:

ContreeProcessSync

Returns:

ContreeProcessSync object with execution results.

read(image_path)

Read file contents from the image.

Parameters:

image_path (str | Path) – Path to the file inside the image.

Return type:

bytes

Returns:

File contents as bytes.

property result: ContreeResult

Execution result. Only available after successful execution.

run(command=None, shell=None, args=None, env=None, cwd=None, hostname=None, stdin=None, stdout=None, stderr=None, tag=None, files=None, timeout=None, disposable=True)

Prepare image for command execution.

Parameters:

• command (str | None) – Command to execute (mutually exclusive with shell).

• shell (str | None) – Shell command string (mutually exclusive with command).

• args (Iterable[str] | None) – Command arguments.

• env (dict[str, str] | None) – Environment variables.

• cwd (str | None) – Working directory inside the image.

• hostname (str | None) – Hostname for the container.

• stdin (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Input source.

• stdout (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Output destination for stdout.

• stderr (Optional[Union`[:py:class:`str, bytes, Path, IO[AnyStr], Literal[-1]]]) – Output destination for stderr.

• tag (str | None) – Tag for the resulting image.

• files (list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None) – Files to upload into the image.

• timeout (float | timedelta | None) – Execution timeout in seconds or as timedelta.

• disposable (bool) – If True, image is discarded after execution.

Return type:

Self

Returns:

New image instance configured for execution.

Raises:

DisposableImageRunError – If attempting to run on a disposed image.

property state: ImageState

Current state of the image in the execution lifecycle.

property stderr: str | bytes | Path | IO | Literal[-1] | None

Stderr output from the execution.

property stdin: IO | None

Configured stdin source.

property stdout: str | bytes | Path | IO | Literal[-1] | None

Stdout output from the execution.

wait()

Execute the prepared command and wait for completion.

Return type:

Self

Returns:

New image instance with execution results.

uuid: UUID | None

Unique identifier of the image.

tag: str | None

Optional tag associated with the image.