Images API

Overview

The Image API allows you to get information about the publicly available images on the CANFAR Science Platform through the CANFAR Harbor Registry. It can be used to get information about all images, or filter by a specific image kind.

Getting Image Information

Get image information

from canfar.images import Images

images = Images()
images.fetch()
[
    "images.canfar.net/canfar/base-3.12:v0.4.1",
    "images.canfar.net/canucs/test:1.2.5",
    "images.canfar.net/canucs/canucs:1.2.9",
    ...,
]

But most of the time, you are only interested in images of a particular type. For example, if you want to get all the images that are available for headless sessions, you can do the following:

Get headless image information

images.fetch(kind="headless")

[
    "images.canfar.net/chimefrb/testing:keep",
    "images.canfar.net/lsst/lsst_v19_0_0:0.1",
    "images.canfar.net/skaha/lensfit:22.11",
    "images.canfar.net/skaha/lensfit:22.10",
    "images.canfar.net/skaha/lensingsim:22.07",
    "images.canfar.net/skaha/phosim:5.6.11",
    "images.canfar.net/skaha/terminal:1.1.2",
    "images.canfar.net/skaha/terminal:1.1.1",
    "images.canfar.net/uvickbos/pycharm:0.1",
    "images.canfar.net/uvickbos/swarp:0.1",
    "images.canfar.net/uvickbos/isis:2.2",
    "images.canfar.net/uvickbos/find_moving:0.1",
]

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]

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]