Shortcuts

Some additional functions are available to perform common tasks that involve multiple API calls under the arkindex.shortcuts module. We recommend using those functions over calling the related APIs yourself when possible.

Uploading an image

The create_image function allows you to upload a local file to the IIIF server managed by Arkindex, then get an Image instance that you can use to create elements on. It goes through the following steps:

  1. Attempt to create the image using CreateImage.

  2. If this API call fails and returns the ID of an existing image, retrieve it with RetrieveImage.

  3. If the status of the image is not checked, use its s3_put_url to upload the file.

  4. Perform an image check using check_image.

Uploading an image using create_image
>>> from arkindex import ArkindexClient, options_from_env
>>> from arkindex.shortcuts import create_image
>>> client = ArkindexClient(**options_from_env())
>>> create_image(client, "/path/to/image.jpg", "destination/image.jpg")
{
    "id": "2c356bf3-96cb-43d5-ba6f-83f85685eaf1",
    "path": "destination/image.jpg",
    "status": "checked",
    ...
}

The optional force_check argument will call check_image with force=True, causing an image check to always run regardless of the image’s status.

Importing an image from an IIIF server

While create_image works with local images and uploads them to the IIIF server of the Arkindex instance, create_iiif_image works with images hosted on other IIIF servers:

  1. Attempt to create the image using CreateIIIFURL.

  2. If this API call fails and returns the ID of an existing image, retrieve it with RetrieveImage.

  3. Perform an image check using check_image.

Importing an image using create_iiif_image
>>> from arkindex import ArkindexClient, options_from_env
>>> from arkindex.shortcuts import create_iiif_image
>>> client = ArkindexClient(**options_from_env())
>>> create_iiif_image(client, "https://iiif.example.com/image.jpg")
{
    "id": "2c356bf3-96cb-43d5-ba6f-83f85685eaf1",
    "path": "image.jpg",
    "url": "https://iiif.example.com/image.jpg",
    "status": "checked",
    "server": {
        "url": "https://iiif.example.com",
        ...
    },
    ...
}

Checking an existing image

The check_image function allows to perform an image check on an image that already exists on the Arkindex instance. This can be used to verify that Arkindex can still reach the image and that it matches the attributes that Arkindex expects.

This function calls the PartialUpdateImage API endpoint. When this API call fails, it will retry once after 10 seconds, and once more after 30 seconds, before abandoning. These long wait times provide margins to avoid overloading IIIF servers.

This function accepts an optional force keyword argument. By default, it only performs the image check when the image is not checked, but when the force argument is set to True, it will always request a new check.

Checking an image using check_image
>>> from arkindex import ArkindexClient, options_from_env
>>> from arkindex.shortcuts import check_image
>>> client = ArkindexClient(**options_from_env())
>>> image = client.request("RetrieveImage", id="2c356bf3-96cb-43d5-ba6f-83f85685eaf1")
>>> check_image(client, image)
{
    "id": "2c356bf3-96cb-43d5-ba6f-83f85685eaf1",
    "path": "destination/image.jpg",
    "status": "checked",
    ...
}