Container Images API

Images lists the Container Images advertised by a CANFAR Science Platform Server. It inherits HTTPClient, so the same saved or runtime credential selection applies.

Image identifiers

from canfar.images import Images

with Images() as images:
    all_images = images.fetch()                 # list[str]
    headless = images.fetch(kind="headless")   # list[str]
    print(headless)

Each string is an image identifier such as images.canfar.net/skaha/terminal:latest. The optional kind is sent as the server's image-type filter.

Parsed image details

Use details() when the digest and supported kinds are needed:

from canfar.images import Images

with Images() as images:
    for image in images.details():
        print(image.id, image.types, image.digest)

details() returns list[canfar.models.containers.Image]; each model has id, types, and digest fields.

API reference

Bases: HTTPClient

CANFAR Image Management.

This class is a subclass of the HTTPClient class and inherits its attributes and methods.

Examples:

>>> from canfar.images import Images
>>> images = Images()
>>> images.fetch()

Source code in canfar/images.py

class Images(HTTPClient):
    """CANFAR Image Management.

    This class is a subclass of the `HTTPClient` class and inherits its
    attributes and methods.

    Examples:
        >>> from canfar.images import Images
        >>> images = Images()
        >>> images.fetch()
    """

    def fetch(self, kind: str | None = None) -> list[str]:
        """Get images from CANFAR Server.

        Args:
            kind (str | None, optional): Type of image. Defaults to None.

        Returns:
            list[str]: A list of images on the server.

        Examples:
            >>> from canfar.images import Images
            >>> images = Images()
            >>> images.fetch(kind="headless")
            ['images.canfar.net/skaha/terminal:1.1.1']
        """
        data: dict[str, str] = {}
        # If kind is not None, add it to the data dictionary
        if kind:
            data["type"] = kind
        response: Response = self.client.get("image", params=data)
        payload: list[dict[str, str]] = response.json()
        return [str(image["id"]) for image in payload]

    def details(self) -> list[Image]:
        """Get image details from CANFAR Server.

        Returns:
            list[Image]: Parsed image details payload from the server.
        """
        response: Response = self.client.get("image")
        payload: list[dict[str, object]] = response.json()
        return [Image.model_validate(item) for item in payload]

details

details()

Get image details from CANFAR Server.

RETURNS	DESCRIPTION
list[Image]	list[Image]: Parsed image details payload from the server.

Source code in canfar/images.py

def details(self) -> list[Image]:
    """Get image details from CANFAR Server.

    Returns:
        list[Image]: Parsed image details payload from the server.
    """
    response: Response = self.client.get("image")
    payload: list[dict[str, object]] = response.json()
    return [Image.model_validate(item) for item in payload]

fetch

fetch(kind=None)

Get images from CANFAR Server.

PARAMETER	DESCRIPTION
kind	Type of image. Defaults to None. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
list[str]	list[str]: A list of images on the server.

Examples:

>>> from canfar.images import Images
>>> images = Images()
>>> images.fetch(kind="headless")
['images.canfar.net/skaha/terminal:1.1.1']

Source code in canfar/images.py

def fetch(self, kind: str | None = None) -> list[str]:
    """Get images from CANFAR Server.

    Args:
        kind (str | None, optional): Type of image. Defaults to None.

    Returns:
        list[str]: A list of images on the server.

    Examples:
        >>> from canfar.images import Images
        >>> images = Images()
        >>> images.fetch(kind="headless")
        ['images.canfar.net/skaha/terminal:1.1.1']
    """
    data: dict[str, str] = {}
    # If kind is not None, add it to the data dictionary
    if kind:
        data["type"] = kind
    response: Response = self.client.get("image", params=data)
    payload: list[dict[str, str]] = response.json()
    return [str(image["id"]) for image in payload]