air_sdk.endpoints.images | DSX Air Documentation

Stub file for images endpoint type hints.

Classes

Name	Description
`MinimumResources`	None
`ImageShare`	None
`Image`	Image model representing a network image.
`ImageEndpointAPI`	API client for image endpoints.
`ImageShareEndpointAPI`	API client for shared image endpoints.

Module Contents

class air_sdk.endpoints.images.MinimumResources

cpu: int

memory: int

storage: int

class air_sdk.endpoints.images.ImageShare

Bases: air_sdk.air_model.AirModel

id: str

created: datetime.datetime

modified: datetime.datetime

image: Image

image_name: str

image_version: str

source_org_display_name: str

target_org_display_name: str

target_org: str

expires_at: datetime.datetime

claimed_by: str

state: str

get_model_api() -> type[ImageShareEndpointAPI]

model_api: ImageShareEndpointAPI

class air_sdk.endpoints.images.Image

Bases: air_sdk.air_model.AirModel

Image model representing a network image.

id: str

Unique identifier for the image

name: str

Human-readable name of the image

version: str

Version of the image

created: datetime.datetime

Timestamp when the image was created

creator: str

User who created the image

modified: datetime.datetime

Timestamp when the image was last modified

mountpoint: str | None

Mountpoint of the image

minimum_resources: MinimumResources

Minimum resources required to run the image

includes_air_agent: bool

Whether the image includes the Air agent

cpu_arch: str

CPU architecture of the image

default_username: str

Default username for the image

default_password: str

Default password for the image

emulation_type: list[str]

The types of emulation the image supports

emulation_version: str

The version of the emulation the image supports

provider: str

Provider of the image

published: bool

Whether the image is published

upload_status: str

Status of the image upload

last_uploaded_at: datetime.datetime | None

Timestamp when the image was last uploaded

size: int

Size of the image

hash: str

Hash of the image

is_owned_by_client: bool

Whether the image is owned by the client

get_model_api() -> type[ImageEndpointAPI]

model_api: ImageEndpointAPI

update(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...,
    default_username: str | dataclasses._MISSING_TYPE = ...,
    default_password: str | dataclasses._MISSING_TYPE = ...,
    mountpoint: str | None | dataclasses._MISSING_TYPE = ...,
    cpu_arch: str | dataclasses._MISSING_TYPE = ...,
    includes_air_agent: bool | dataclasses._MISSING_TYPE = ...,
    emulation_type: list[str] | dataclasses._MISSING_TYPE = ...,
    emulation_version: str | dataclasses._MISSING_TYPE = ...,
    provider: str | dataclasses._MISSING_TYPE = ...
) -> None

Update the image’s properties.

Example:

>>> image.update(name='new-name', version='1.0.0')
>>> image.update(default_username='user', default_password='pass')

Parameters:

name – Name of the image
version – Version of the image
default_username – Default username for the image
default_password – Default password for the image
mountpoint – Mountpoint of the image
cpu_arch – CPU architecture of the image
includes_air_agent – Whether the image includes the Air agent
emulation_type – The types of emulation the image supports
emulation_version – The version of the emulation the image supports
provider – Provider of the image

upload(
    *,
    filepath: str | pathlib.Path,
    timeout: datetime.timedelta | None | dataclasses._MISSING_TYPE = ...,
    max_workers: int | dataclasses._MISSING_TYPE = ...
) -> Image

Upload the image to the Air platform.

All uploads use multipart upload to S3. Parts are ~100MB each, calculated automatically by the API.

Parameters:

filepath – local file path to the image
timeout – Timeout per part upload (default: DEFAULT_UPLOAD_TIMEOUT).
max_workers – number of concurrent workers for parallel uploads (default: 1 for sequential).

Example:

>>> image.upload(filepath='local_file_path')

Returns:

the uploaded image instance

clear_upload() -> Image

Clear the upload status of the image.

Example:

>>> image.clear_upload()

Returns:

the image instance

publish(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image

Publish the image.

Parameters:

name – new name of the image
version – new version of the image

Example:

>>> image.publish()
>>> image.publish(name='new-name', version='1.0.0')

Returns:

the published image instance

unpublish(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image

Unpublish the image.

Parameters:

name – new name of the image
version – new version of the image

Example:

>>> image.unpublish()
>>> image.unpublish(name='new-name', version='1.0.0')

Returns:

the image instance

share(
    *,
    target_org: str,
    expires_at: datetime.datetime | dataclasses._MISSING_TYPE = ...
) -> ImageShare

Share the image with another organization.

Parameters:

target_org – The NGC org name of the organization receiving the image
expires_at – The date and time the image share expires

Example:

>>> share = image.share(target_org='target-org-name')

Returns:

The created share instance

class air_sdk.endpoints.images.ImageEndpointAPI

Bases: air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.images.Image]

API client for image endpoints.

API_PATH: str

model: type[Image]

create(
    *,
    name: str,
    version: str,
    default_username: str,
    default_password: str,
    mountpoint: str | None | dataclasses._MISSING_TYPE = ...,
    cpu_arch: str | dataclasses._MISSING_TYPE = ...,
    includes_air_agent: bool | dataclasses._MISSING_TYPE = ...,
    emulation_type: list[str] | dataclasses._MISSING_TYPE = ...,
    emulation_version: str | dataclasses._MISSING_TYPE = ...,
    provider: str | dataclasses._MISSING_TYPE = ...,
    filepath: str | pathlib.Path | dataclasses._MISSING_TYPE = ...,
    timeout: datetime.timedelta | None | dataclasses._MISSING_TYPE = ...,
    max_workers: int | dataclasses._MISSING_TYPE = ...
) -> Image

Create a new image.

Parameters:

name – Name of the image
version – Version of the image
default_username – Default username for the image
default_password – Default password for the image
mountpoint – Mountpoint of the image
cpu_arch – CPU architecture of the image
includes_air_agent – Whether the image includes the Air agent
emulation_type – The types of emulation the image supports
emulation_version – The version of the emulation the image supports
provider – Provider of the image
filepath – Optional path to image file. If provided, uploads the image after creation using upload.
timeout – Timeout per part upload (default: DEFAULT_UPLOAD_TIMEOUT). Only used if filepath is provided.
max_workers – Number of concurrent workers for parallel uploads (default: 1). Only used if filepath is provided.

Example:

>>> # Create image without upload
>>> api.images.create(
...     name='cumulus-vx-1.2.3',
...     version='1.0.0',
...     default_username='user',
...     default_password='password',
... )
>>> # Create and upload image in single step
>>> api.images.create(
...     name='cumulus-vx-1.2.3',
...     version='1.0.0',
...     default_username='user',
...     default_password='password',
...     filepath='./cumulus-vx.qcow2',
... )
>>> # Create and upload with parallel workers
>>> api.images.create(
...     name='cumulus-vx-1.2.3',
...     version='1.0.0',
...     default_username='user',
...     default_password='password',
...     filepath='./large-image.qcow2',
...     max_workers=4,
... )

Returns:

The created Image instance

list(
    *,
    name: str = ...,
    version: str = ...,
    cpu_arch: Literal[x86, ARM] = ...,
    creator: str = ...,
    includes_air_agent: bool = ...,
    provider: Literal[VM, CONTAINER] = ...,
    published: bool = ...,
    upload_status: Literal[READY, UPLOADING, VALIDATING, COMPLETED, PUBLISHED, UNPUBLISHED, UNPUBLISHING, COPYING_FROM_IMAGE_SHARE] = ...,
    hash: str = ...,
    is_owned_by_client: bool = ...,
    limit: int = ...,
    offset: int = ...,
    ordering: str = ...,
    search: str = ...
) -> Iterator[Image]

List all images with optional filtering.

Parameters:

name – Name of the image
version – Version of the image
cpu_arch – CPU architecture of the image
creator – Creator of the image
includes_air_agent – Whether the image includes the Air agent
emulation_type – The types of emulation the image supports
emulation_version – The version of the emulation the image supports
provider – Provider of the image
published – Whether the image is published
upload_status – Status of the image upload
last_uploaded_at – Timestamp when the image was last uploaded
hash – Hash of the image
is_owned_by_client – Whether the image is owned by the client
limit – Maximum number of results to return
offset – Offset for pagination
ordering – Ordering of the results
search – Search query

Example:

>>> for image in api.images.list():
...     print(image.name)
>>> # Filter by name
>>> for image in api.images.list(search='image-name'):
...     print(image.name)
>>> # Order by name descending
>>> for image in api.images.list(ordering='-name'):
...     print(image.name)

Returns:

Iterator of Image instances

get(pk: PrimaryKey) -> Image

Get a specific image by ID.

Parameters:

pk – The image ID (string or UUID)

Example:

>>> image = api.images.get('image-id')

Returns:

The Image instance

upload(
    *,
    image: Image | PrimaryKey,
    filepath: str | pathlib.Path,
    timeout: datetime.timedelta | None | dataclasses._MISSING_TYPE = ...,
    max_workers: int | dataclasses._MISSING_TYPE = ...
) -> Image

Upload the image to the Air platform.

All uploads use multipart upload to S3. Parts are ~100MB each, calculated automatically by the API.

Parameters:

image – Image instance or image ID
filepath – Path to the file to upload
timeout – Timeout per part upload (default: DEFAULT_UPLOAD_TIMEOUT). This timeout applies to EACH part upload (not total operation).
max_workers – Number of concurrent workers for uploads. Default: 1 (sequential uploads). Set > 1 for parallel uploads.

Returns:

Updated Image instance

Example:

>>> # File upload
>>> image.upload(filepath='image.qcow2')
>>> # Large file with parallel upload
>>> image.upload(filepath='large.qcow2', max_workers=4)

Raises:

FileNotFoundError – If the file does not exist
ValueError – If filepath is not a regular file or max_workers < 1
PermissionError – If the file is not readable
AirUnexpectedResponse – If upload fails or backend returns invalid data
requests.RequestException – For network/HTTP errors

clear_upload(
    *,
    image: Image | PrimaryKey
) -> None

Clear the upload status of the image.

Parameters:

image – image to clear upload

Example:

>>> api.images.clear_upload(image)

Returns:

None

publish(
    *,
    image: Image | PrimaryKey,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image

Publish the image.

Args:

Required parameters: image: image to publish

Optional Parameters: name: The name of the image version: The version of the image

Returns:

None

Example:

>>> api.images.publish(image)

unpublish(
    *,
    image: Image | PrimaryKey,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image

Unpublish the image.

Parameters:

image – image to unpublish (Image instance or image ID)
name – new name of the image
version – new version of the image

Example:

>>> api.images.unpublish(image)
>>> api.images.unpublish(image, name='new-name', version='new-version')

Returns:

the unpublished image instance

share(
    *,
    image: Image | PrimaryKey,
    target_org: str,
    expires_at: datetime.datetime | dataclasses._MISSING_TYPE = ...
) -> ImageShare

Share the image with another organization.

Args:

Required parameters: image: The image to share (Image instance or image ID) target_org: The NGC org name of the organization receiving the image

Optional parameters: expires_at: The date and time the image share expires

Returns:

ImageShare: The created share object

Example:

>>> share = api.images.share(image='image-id', target_org='target-org-name')

claim_image_share(
    *,
    image_share: PrimaryKey,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image

Claim a shared image into your organization.

Parameters:

image_share – The share ID to claim (string or UUID)
name – new name of the image
version – new version of the image

Example:

>>> image = api.images.claim_image_share(image_share='share-id')
>>> image = api.images.claim_image_share(
...     image_share='share-id', name='new-name', version='1.0.0'
... )

Returns:

The claimed image

shares: ImageShareEndpointAPI

Access the image shares API.

Returns:

ImageShareEndpointAPI: The API for managing image shares

Example:

>>> # List all shared images
>>> for share in api.images.shares.list():
...     print(share.image_name)
>>> # Create a new share
>>> share = api.images.shares.create(
...     image='image-id',
...     target_org='target-org-name',
... )
>>> # Get a specific share
>>> share = api.images.shares.get('share-id')
>>> # Delete a share
>>> api.images.shares.delete('share-id')

class air_sdk.endpoints.images.ImageShareEndpointAPI

Bases: air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.images.ImageShare]

API client for shared image endpoints.

API_PATH: str

model: type[ImageShare]

list(
    *,
    limit: int | dataclasses._MISSING_TYPE = ...,
    offset: int | dataclasses._MISSING_TYPE = ...,
    ordering: str | dataclasses._MISSING_TYPE = ...,
    search: str | dataclasses._MISSING_TYPE = ...
) -> Iterator[ImageShare]

List all shared images.

Parameters:

limit – Maximum number of results to return
offset – Offset for pagination
ordering – Ordering of the results
search – Search query

Example:

>>> # List all shared images
>>> for share in api.images.shares.list():
...     print(share.image_name)
>>> # Filter by image name
>>> for share in api.images.shares.list(search='image-name'):
...     print(share.image_name)
>>> # Order by image name descending
>>> for share in api.images.shares.list(ordering='-image_name'):
...     print(share.image_name)

Returns:

Iterator of ImageShare instances

create(
    *,
    image: Image | PrimaryKey,
    target_org: str,
    expires_at: datetime.datetime | dataclasses._MISSING_TYPE = ...
) -> ImageShare

Create a new image share.

Parameters:

image – The image or image ID to share
target_org – The NGC org name of the organization receiving the image
expires_at – The date and time the image share expires

Example:

>>> share = api.images.shares.create(
...     image='image-id', target_org='target-org-name'
... )

Returns:

The created image share instance

get(pk: PrimaryKey) -> ImageShare

Get a specific shared image by ID.

Parameters:

pk – The image share ID (string or UUID)

Example:

>>> share = api.images.shares.get('share-id')

Returns:

The ImageShare instance

delete(pk: PrimaryKey) -> None

Delete (unshare) an image share.

Parameters:

pk – The share ID to delete (string or UUID)

Example:

>>> api.images.shares.delete('share-id')
>>> api.images.shares.delete(share.id)

Returns:

None