Image helpers

See Import a Docker image and Build a Docker image for complete programs. These helpers use the same connection sources as the sandbox factory. A supplied client, cache, or store remains owned by the caller.

Import and build sandbox images with managed clients and persistent caches.

Each helper returns a ConTree image UUID for create_sandbox_session. Connection settings follow the sandbox factory. Supplied clients and stores remain caller-owned; helpers close only the resources they create.

contree_sdk.images.image_cache_directory(cache_dir=None)

Select the image store directory without creating it.

Return type:

Path

Returns:

The explicit directory or $XDG_CACHE_HOME/contree (default ~/.cache/contree).

contree_sdk.images.sync_import_image(source, *, tag=None, timeout=300, no_cache=False, store=None, cache_dir=None, cache_ttl=3600, url=None, project=None, token=None, auth_type=None, profile=None, config_path=None, client=None, client_type=None, **client_kwargs)

Import a registry image and wait for a usable filesystem image.

Registry names such as alpine:latest and docker:// URLs are accepted. Pass ImageImportRegistry for registry credentials. Results are cached for one hour by default. no_cache=True imports again and refreshes the cached result. A requested tag is reapplied on cache hits. Timeout or interruption after submission requests cancellation of the import operation. Import failure or a missing result image raises FailedOperationError.

Return type:

str

Returns:

The imported ConTree image UUID.

Raises:

• TypeError – A supplied component uses the wrong execution mode.

• ValueError – The source, timeout, TTL, or connection settings are invalid.

async contree_sdk.images.async_import_image(source, *, tag=None, timeout=300, no_cache=False, store=None, cache_dir=None, cache_ttl=3600, url=None, project=None, token=None, auth_type=None, profile=None, config_path=None, client=None, client_type=None, **client_kwargs)

Import a registry image and wait for a usable filesystem image.

Registry names such as alpine:latest and docker:// URLs are accepted. Pass ImageImportRegistry for registry credentials. Results are cached for one hour by default. no_cache=True imports again and refreshes the cached result. A requested tag is reapplied on cache hits. Timeout or interruption after submission requests cancellation of the import operation. Import failure or a missing result image raises FailedOperationError.

Return type:

str

Returns:

The imported ConTree image UUID.

Raises:

• TypeError – A supplied component uses the wrong execution mode.

• ValueError – The source, timeout, TTL, or connection settings are invalid.

contree_sdk.images.sync_build_image(context, *, dockerfile=None, tag=None, build_args=None, no_cache=False, timeout=600, session_id=None, store=None, cache_dir=None, on_event=None, on_step=None, builder_type=<class 'contree_sdk.docker.sync.ContreeDockerBuilder'>, builder_kwargs=None, url=None, project=None, token=None, auth_type=None, profile=None, config_path=None, client=None, client_type=None, **client_kwargs)

Build a Dockerfile with persistent layer history and upload caching.

The default Dockerfile is context/Dockerfile. A SQLite store in the XDG cache directory holds history and reusable results unless supplied explicitly. no_cache=True disables layer reuse; content-addressed uploads remain cached. Use builder_type and builder_kwargs to extend the existing Docker builder. The connection scope is part of the default build session identity. Invalid inputs raise ValueError; failed build steps raise DockerBuildError.

Return type:

str

Returns:

The built ConTree filesystem image UUID.

Raises:

TypeError – A supplied component uses the wrong execution mode.

async contree_sdk.images.async_build_image(context, *, dockerfile=None, tag=None, build_args=None, no_cache=False, timeout=600, session_id=None, store=None, cache_dir=None, on_event=None, on_step=None, builder_type=<class 'contree_sdk.docker.asyncio.ContreeAsyncDockerBuilder'>, builder_kwargs=None, url=None, project=None, token=None, auth_type=None, profile=None, config_path=None, client=None, client_type=None, **client_kwargs)

Build a Dockerfile with persistent layer history and upload caching.

The default Dockerfile is context/Dockerfile. A SQLite store in the XDG cache directory holds history and reusable results unless supplied explicitly. no_cache=True disables layer reuse; content-addressed uploads remain cached. Use builder_type and builder_kwargs to extend the existing Docker builder. The connection scope is part of the default build session identity. Invalid inputs raise ValueError; failed build steps raise DockerBuildError.

Return type:

str

Returns:

The built ConTree filesystem image UUID.

Raises:

TypeError – A supplied component uses the wrong execution mode.