Skip to content

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.

Parameters:

Name Type Description Default
HTTPClient HTTPClient

Configured HTTP Client.

 required

Returns:

Name Type Description
Images

CANFAR Image Management Object.
Source code in canfar/images.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
class Images(HTTPClient):
    """CANFAR Image Management.

    Args:
        HTTPClient (canfar.client.HTTPClient): Configured HTTP Client.

    Returns:
        Images: CANFAR Image Management Object.
    """

    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(kind=None)

Get images from CANFAR Server.

Parameters:

Name Type Description Default
kind str | None

Type of image. Defaults to None.

 None

Returns:

Type 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 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
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]