Sessions

class contree_sdk.sdk.objects.session.ContreeSession(image)[source]
async download(image_path, local_path=None)

Download a file from the image to local filesystem.

Parameters:

  • image_path (str | PurePosixPath) – 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 | PurePosixPath) – 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.

Raises:

RuntimeError – If the result hasn’t been set.

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, truncate_output_at=None)

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[str], IO[bytes], Literal[-1]]]) – Input source.

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

  • stderr (Optional[Union`[:py:class:`str, bytes, Path, IO[str], IO[bytes], Literal[-1], type[str | bytes]]]) – 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.

  • truncate_output_at (int | None) – number of bytes to truncate stdout and stderr. Defaults to default_truncate_output_at

Return type:

TypeVar(_T, bound= _ImageLikeBase)

Returns:

New image instance configured for execution.

Raises:

  • DisposableImageRunError – If attempting to run on a disposed image.

  • ValueError – If neither command nor shell is provided.

property state: ImageState

Current state of the image in the execution lifecycle.

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

Stderr output from the execution.

property stdin: IO | None

Configured stdin source.

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

Stdout output from the execution.

async tag_as(tag)

Tag this image with the specified tag, or remove the tag if None.

Parameters:

tag (str | None) – Tag name to apply to the image, or None to remove the tag.

Return type:

TypeVar(_T, bound= _ImageLikeBase)

Returns:

New instance with updated tag.

async untag()

Remove the tag from this image.

Return type:

TypeVar(_T, bound= _ImageLikeBase)

Returns:

New instance with tag set to None.

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)[source]
download(image_path, local_path=None)

Download a file from the image to local filesystem.

Parameters:

  • image_path (str | PurePosixPath) – 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 | PurePosixPath) – 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] | str | None) – Command and arguments list.

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

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

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

  • stderr (Optional[Union`[:py:class:`str, bytes, Path, IO[str], IO[bytes], 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.

Raises:

RuntimeError – If the result hasn’t been set.

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, truncate_output_at=None)

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[str], IO[bytes], Literal[-1]]]) – Input source.

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

  • stderr (Optional[Union`[:py:class:`str, bytes, Path, IO[str], IO[bytes], Literal[-1], type[str | bytes]]]) – 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.

  • truncate_output_at (int | None) – number of bytes to truncate stdout and stderr. Defaults to default_truncate_output_at

Return type:

TypeVar(_T, bound= _ImageLikeBase)

Returns:

New image instance configured for execution.

Raises:

  • DisposableImageRunError – If attempting to run on a disposed image.

  • ValueError – If neither command nor shell is provided.

property state: ImageState

Current state of the image in the execution lifecycle.

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

Stderr output from the execution.

property stdin: IO | None

Configured stdin source.

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

Stdout output from the execution.

tag_as(tag)

Tag this image with the specified tag, or remove the tag if None.

Parameters:

tag (str | None) – Tag name to apply to the image, or None to remove the tag.

Return type:

TypeVar(_T, bound= _ImageLikeBase)

Returns:

New instance with updated tag.

untag()

Remove the tag from this image.

Return type:

TypeVar(_T, bound= _ImageLikeBase)

Returns:

New instance with tag set to None.

wait()

Execute the prepared command and wait for completion.

Return type:

TypeVar(_T, bound= _ImageLikeSync)

Returns:

New image instance with execution results.

uuid: UUID | None

Unique identifier of the image.

tag: str | None

Optional tag associated with the image.