Images Manager

class contree_sdk.sdk.managers.images.ImagesManager(client)

async __aiter__()

async __call__(number=100, kind=None, tagged=False, since=None, until=None)

Fetch a list of images with optional filters.

Parameters:

• number (int | None) – Maximum number of images to return. None returns all.

• kind (ImageKind | None) – Filter by image kind.

• tagged (bool) – If True, return only tagged images.

• since (datetime | timedelta | None) – Return images created after this time. Accepts datetime or timedelta relative to now.

• until (datetime | timedelta | None) – Return images created before this time. Accepts datetime or timedelta relative to now.

Return type:

list[TypeVar(_ImageT, bound= _ContreeImageBase)]

Returns:

List of images matching the given filters.

async docker(ref, *, tag=None, username=None, password=None, timeout=None)

Resolve an image by tag, falling back to import if not found.

Derives the target tag from the tag parameter or from the reference itself, then tries to find an existing image with that tag. If the image does not exist, triggers an import and returns the result.

Parameters:

• ref (str | OCIReference | UUID) – UUID, OCI reference string, or OCIReference of the image.

• tag (str | None) – Tag override; if provided, replaces the tag from the reference.

• username (str | None) – Registry username for authenticated imports.

• password (str | None) – Registry password for authenticated imports.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Resolved or imported image object.

Raises:

NotFoundError – If ref is a UUID and the image does not exist.

async import_from(image, *, tag=None, username=None, password=None, timeout=None)

Import an image from an external registry into Contree.

Parameters:

• image (str | OCIReference) – OCI reference string or OCIReference pointing to the source image.

• tag (str | None) – Tag to assign to the imported image. Defaults to the tag in the reference.

• username (str | None) – Registry username for private registries.

• password (str | None) – Registry password for private registries.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Imported image object.

Raises:

• ValueError – If image is a UUID or credentials are incomplete.

• FailedOperationError – If the import operation completes without returning an image.

async oci(ref, *, tag=None, username=None, password=None, timeout=None)

Resolve an image by tag, falling back to import if not found.

Derives the target tag from the tag parameter or from the reference itself, then tries to find an existing image with that tag. If the image does not exist, triggers an import and returns the result.

Parameters:

• ref (str | OCIReference | UUID) – UUID, OCI reference string, or OCIReference of the image.

• tag (str | None) – Tag override; if provided, replaces the tag from the reference.

• username (str | None) – Registry username for authenticated imports.

• password (str | None) – Registry password for authenticated imports.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Resolved or imported image object.

Raises:

NotFoundError – If ref is a UUID and the image does not exist.

async podman(ref, *, tag=None, username=None, password=None, timeout=None)

Resolve an image by tag, falling back to import if not found.

Derives the target tag from the tag parameter or from the reference itself, then tries to find an existing image with that tag. If the image does not exist, triggers an import and returns the result.

Parameters:

• ref (str | OCIReference | UUID) – UUID, OCI reference string, or OCIReference of the image.

• tag (str | None) – Tag override; if provided, replaces the tag from the reference.

• username (str | None) – Registry username for authenticated imports.

• password (str | None) – Registry password for authenticated imports.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Resolved or imported image object.

Raises:

NotFoundError – If ref is a UUID and the image does not exist.

async pull(url_or_tag_or_uuid, *, new_tag=None, username=None, password=None, timeout=None)

Return type:

ContreeImage

async pull_by_oci(ref, *, tag=None, username=None, password=None, timeout=None)

Resolve an image by tag, falling back to import if not found.

Derives the target tag from the tag parameter or from the reference itself, then tries to find an existing image with that tag. If the image does not exist, triggers an import and returns the result.

Parameters:

• ref (str | OCIReference | UUID) – UUID, OCI reference string, or OCIReference of the image.

• tag (str | None) – Tag override; if provided, replaces the tag from the reference.

• username (str | None) – Registry username for authenticated imports.

• password (str | None) – Registry password for authenticated imports.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Resolved or imported image object.

Raises:

NotFoundError – If ref is a UUID and the image does not exist.

async use(ref, strict=False)

Resolve a reference to an image object without importing.

Parameters:

• ref (str | UUID | OCIReference) – Image identifier — UUID, OCI reference string, or OCIReference object.

• strict (bool) – If True, verify the image exists by fetching it from the API.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Image object corresponding to the given reference.

class contree_sdk.sdk.managers.images.ImagesManagerSync(client)

__call__(number=100, kind=None, tagged=False, since=None, until=None)

Fetch a list of images with optional filters.

Parameters:

• number (int | None) – Maximum number of images to return. None returns all.

• kind (ImageKind | None) – Filter by image kind.

• tagged (bool) – If True, return only tagged images.

• since (datetime | timedelta | None) – Return images created after this time. Accepts datetime or timedelta relative to now.

• until (datetime | timedelta | None) – Return images created before this time. Accepts datetime or timedelta relative to now.

Return type:

list[TypeVar(_ImageT, bound= _ContreeImageBase)]

Returns:

List of images matching the given filters.

__iter__()

docker(ref, *, tag=None, username=None, password=None, timeout=None)

Resolve an image by tag, falling back to import if not found.

Derives the target tag from the tag parameter or from the reference itself, then tries to find an existing image with that tag. If the image does not exist, triggers an import and returns the result.

Parameters:

• ref (str | OCIReference | UUID) – UUID, OCI reference string, or OCIReference of the image.

• tag (str | None) – Tag override; if provided, replaces the tag from the reference.

• username (str | None) – Registry username for authenticated imports.

• password (str | None) – Registry password for authenticated imports.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Resolved or imported image object.

Raises:

NotFoundError – If ref is a UUID and the image does not exist.

import_from(image, *, tag=None, username=None, password=None, timeout=None)

Import an image from an external registry into Contree.

Parameters:

• image (str | OCIReference) – OCI reference string or OCIReference pointing to the source image.

• tag (str | None) – Tag to assign to the imported image. Defaults to the tag in the reference.

• username (str | None) – Registry username for private registries.

• password (str | None) – Registry password for private registries.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Imported image object.

Raises:

• ValueError – If image is a UUID or credentials are incomplete.

• FailedOperationError – If the import operation completes without returning an image.

oci(ref, *, tag=None, username=None, password=None, timeout=None)

Resolve an image by tag, falling back to import if not found.

Derives the target tag from the tag parameter or from the reference itself, then tries to find an existing image with that tag. If the image does not exist, triggers an import and returns the result.

Parameters:

• ref (str | OCIReference | UUID) – UUID, OCI reference string, or OCIReference of the image.

• tag (str | None) – Tag override; if provided, replaces the tag from the reference.

• username (str | None) – Registry username for authenticated imports.

• password (str | None) – Registry password for authenticated imports.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Resolved or imported image object.

Raises:

NotFoundError – If ref is a UUID and the image does not exist.

podman(ref, *, tag=None, username=None, password=None, timeout=None)

Resolve an image by tag, falling back to import if not found.

Derives the target tag from the tag parameter or from the reference itself, then tries to find an existing image with that tag. If the image does not exist, triggers an import and returns the result.

Parameters:

• ref (str | OCIReference | UUID) – UUID, OCI reference string, or OCIReference of the image.

• tag (str | None) – Tag override; if provided, replaces the tag from the reference.

• username (str | None) – Registry username for authenticated imports.

• password (str | None) – Registry password for authenticated imports.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Resolved or imported image object.

Raises:

NotFoundError – If ref is a UUID and the image does not exist.

pull(url_or_tag_or_uuid, *, new_tag=None, username=None, password=None, timeout=None)

Return type:

ContreeImageSync

pull_by_oci(ref, *, tag=None, username=None, password=None, timeout=None)

Resolve an image by tag, falling back to import if not found.

Derives the target tag from the tag parameter or from the reference itself, then tries to find an existing image with that tag. If the image does not exist, triggers an import and returns the result.

Parameters:

• ref (str | OCIReference | UUID) – UUID, OCI reference string, or OCIReference of the image.

• tag (str | None) – Tag override; if provided, replaces the tag from the reference.

• username (str | None) – Registry username for authenticated imports.

• password (str | None) – Registry password for authenticated imports.

• timeout (float | None) – Maximum seconds to wait for the import operation.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Resolved or imported image object.

Raises:

NotFoundError – If ref is a UUID and the image does not exist.

use(ref, strict=False)

Resolve a reference to an image object without importing.

Parameters:

• ref (str | UUID | OCIReference) – Image identifier — UUID, OCI reference string, or OCIReference object.

• strict (bool) – If True, verify the image exists by fetching it from the API.

Return type:

TypeVar(_ImageT, bound= _ContreeImageBase)

Returns:

Image object corresponding to the given reference.