Skip to main content

​
class ContreeSession

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

​
Attributes

​
elapsed
timedelta
Time elapsed during execution.
​
exit_code
int
Exit code of the executed command.
​
result
ContreeResult
Execution result. Only available after successful execution.
  • Raises — RuntimeError – If the result hasn’t been set.
​
state
ImageState
Current state of the image in the execution lifecycle.
​
stderr
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | None
Stderr output from the execution.
​
stdin
IO | None
Configured stdin source.
​
stdout
str | bytes | Path | IO[str] | IO[bytes] | 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.

​
Methods

​
apply_files()

async def apply_files(*args, files) -> TypeVar(_T, bound= _ImageLikeBase)
Upload files into a new image derived from this one.
​
*args
str | Path | UploadFileSpec | list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec]
Files to upload.
​
files
list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None
default:"None"
Files as a list or a dict mapping destination paths to sources. When both args and files are provided, they are merged.
​
returns
TypeVar(_T, bound= _ImageLikeBase)
New image with the uploaded files baked in.

​
download()

async def download(image_path, local_path) -> Path | None
Download a file from the image to local filesystem.
​
image_path
str | PurePosixPath
required
Path to the file inside the image.
​
local_path
str | Path | None
default:"None"
Local destination path. Defaults to filename from image_path.
​
returns
Path | None
Path to the downloaded file.

​
ls()

async def ls(path) -> list[ImageFile | ImageDirectory]
List files and directories at the given path.
​
path
str | PurePosixPath
default:"'/'"
Path inside the image to list.
​
returns
list[ImageFile | ImageDirectory]
list[ImageFile | ImageDirectory]List of ImageFile and ImageDirectory objects.

​
read()

async def read(image_path) -> bytes
Read file contents from the image.
​
image_path
str | Path
required
Path to the file inside the image.
​
returns
bytes
File contents as bytes.

​
run()

def run(command, *, shell, args, env, cwd, hostname, stdin, stdout, stderr, tag, files, timeout, disposable, truncate_output_at) -> TypeVar(_T, bound= _ImageLikeBase)
Prepare image for command execution.
​
command
str | None
default:"None"
Command to execute (mutually exclusive with shell).
​
shell
str | None
default:"None"
Shell command string (mutually exclusive with command).
​
args
Iterable[str] | None
default:"None"
Command arguments.
​
env
dict[str, str] | None
default:"None"
Environment variables.
​
cwd
str | None
default:"None"
Working directory inside the image.
​
hostname
str | None
default:"None"
Hostname for the container.
​
stdin
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | None
default:"None"
Input source.
​
stdout
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | type[str | bytes] | None
default:"None"
Output destination for stdout.
​
stderr
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | type[str | bytes] | None
default:"None"
Output destination for stderr.
​
tag
str | None
default:"None"
Tag for the resulting image.
​
files
list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None
default:"None"
Files to upload into the image.
​
timeout
float | timedelta | None
default:"None"
Execution timeout in seconds or as timedelta.
​
disposable
bool
default:"True"
If True, image is discarded after execution.
​
truncate_output_at
int | None
default:"None"
number of bytes to truncate stdout and stderr. Defaults to default_truncate_output_at
​
returns
TypeVar(_T, bound= _ImageLikeBase)
New image instance configured for execution.
​
raises
DisposableImageRunError – If attempting to run on a disposed image.
​
raises
ValueError – If neither command nor shell is provided.

​
tag_as()

async def tag_as(tag) -> TypeVar(_T, bound= _ImageLikeBase)
Tag this image with the specified tag, or remove the tag if None.
​
tag
str | None
required
Tag name to apply to the image, or None to remove the tag.
​
returns
TypeVar(_T, bound= _ImageLikeBase)
New instance with updated tag.

​
untag()

async def untag() -> TypeVar(_T, bound= _ImageLikeBase)
Remove the tag from this image.
​
returns
TypeVar(_T, bound= _ImageLikeBase)
New instance with tag set to None.

​
class ContreeSessionSync

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

​
Attributes

​
elapsed
timedelta
Time elapsed during execution.
​
exit_code
int
Exit code of the executed command.
​
result
ContreeResult
Execution result. Only available after successful execution.
  • Raises — RuntimeError – If the result hasn’t been set.
​
state
ImageState
Current state of the image in the execution lifecycle.
​
stderr
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | None
Stderr output from the execution.
​
stdin
IO | None
Configured stdin source.
​
stdout
str | bytes | Path | IO[str] | IO[bytes] | 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.

​
Methods

​
apply_files()

def apply_files(*args, files) -> TypeVar(_T, bound= _ImageLikeBase)
Upload files into a new image derived from this one.
​
*args
str | Path | UploadFileSpec | list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec]
Files to upload.
​
files
list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None
default:"None"
Files as a list or a dict mapping destination paths to sources. When both args and files are provided, they are merged.
​
returns
TypeVar(_T, bound= _ImageLikeBase)
New image with the uploaded files baked in.

​
download()

def download(image_path, local_path) -> Path | None
Download a file from the image to local filesystem.
​
image_path
str | PurePosixPath
required
Path to the file inside the image.
​
local_path
str | Path | None
default:"None"
Local destination path. Defaults to filename from image_path.
​
returns
Path | None
Path to the downloaded file.

​
ls()

def ls(path) -> list[ImageFileSync | ImageDirectorySync]
List files and directories at the given path.
​
path
str | PurePosixPath
default:"'/'"
Path inside the image to list.
​
returns
list[ImageFileSync | ImageDirectorySync]
list[ImageFileSync | ImageDirectorySync]List of ImageFileSync and ImageDirectorySync objects.

​
popen()

def popen(args, *, stdin, input, stdout, stderr, shell, cwd, timeout, check, text, env) -> ContreeProcessSync
Run a command with subprocess-like interface.
​
args
list[str] | str | None
default:"None"
Command and arguments list.
​
stdin
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | None
default:"None"
Input source.
​
input
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | None
default:"None"
Alternative input source (alias for stdin).
​
stdout
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | None
default:"None"
Output destination for stdout.
​
stderr
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | None
default:"None"
Output destination for stderr.
​
shell
bool
default:"False"
If True, treat args as shell command.
​
cwd
str | None
default:"None"
Working directory inside the image.
​
timeout
float | None
default:"None"
Execution timeout in seconds.
​
check
bool
default:"False"
If True, raise on non-zero exit code.
​
text
bool | None
default:"None"
If True, decode output as text.
​
env
dict[str, str] | None
default:"None"
Environment variables.
​
returns
ContreeProcessSync
ContreeProcessSyncContreeProcessSync object with execution results.

​
read()

def read(image_path) -> bytes
Read file contents from the image.
​
image_path
str | Path
required
Path to the file inside the image.
​
returns
bytes
File contents as bytes.

​
run()

def run(command, *, shell, args, env, cwd, hostname, stdin, stdout, stderr, tag, files, timeout, disposable, truncate_output_at) -> TypeVar(_T, bound= _ImageLikeBase)
Prepare image for command execution.
​
command
str | None
default:"None"
Command to execute (mutually exclusive with shell).
​
shell
str | None
default:"None"
Shell command string (mutually exclusive with command).
​
args
Iterable[str] | None
default:"None"
Command arguments.
​
env
dict[str, str] | None
default:"None"
Environment variables.
​
cwd
str | None
default:"None"
Working directory inside the image.
​
hostname
str | None
default:"None"
Hostname for the container.
​
stdin
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | None
default:"None"
Input source.
​
stdout
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | type[str | bytes] | None
default:"None"
Output destination for stdout.
​
stderr
str | bytes | Path | IO[str] | IO[bytes] | Literal[-1] | type[str | bytes] | None
default:"None"
Output destination for stderr.
​
tag
str | None
default:"None"
Tag for the resulting image.
​
files
list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None
default:"None"
Files to upload into the image.
​
timeout
float | timedelta | None
default:"None"
Execution timeout in seconds or as timedelta.
​
disposable
bool
default:"True"
If True, image is discarded after execution.
​
truncate_output_at
int | None
default:"None"
number of bytes to truncate stdout and stderr. Defaults to default_truncate_output_at
​
returns
TypeVar(_T, bound= _ImageLikeBase)
New image instance configured for execution.
​
raises
DisposableImageRunError – If attempting to run on a disposed image.
​
raises
ValueError – If neither command nor shell is provided.

​
tag_as()

def tag_as(tag) -> TypeVar(_T, bound= _ImageLikeBase)
Tag this image with the specified tag, or remove the tag if None.
​
tag
str | None
required
Tag name to apply to the image, or None to remove the tag.
​
returns
TypeVar(_T, bound= _ImageLikeBase)
New instance with updated tag.

​
untag()

def untag() -> TypeVar(_T, bound= _ImageLikeBase)
Remove the tag from this image.
​
returns
TypeVar(_T, bound= _ImageLikeBase)
New instance with tag set to None.

​
wait()

def wait() -> TypeVar(_T, bound= _ImageLikeSync)
Execute the prepared command and wait for completion.
​
returns
TypeVar(_T, bound= _ImageLikeSync)
New image instance with execution results.