air_sdk.endpoints.images#

Stub file for images endpoint type hints.

Classes#

`MinimumResources`
`ImageShare`	Helper class that provides a standard way to create an ABC using
`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[source]#

cpu: int#

memory: int#

storage: int#

class air_sdk.endpoints.images.ImageShare[source]#

Bases: air_sdk.air_model.AirModel

Helper class that provides a standard way to create an ABC using inheritance.

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#

classmethod get_model_api() → type[ImageShareEndpointAPI][source]#: Returns the respective AirModelAPI type for this model.

property model_api: ImageShareEndpointAPI#

class air_sdk.endpoints.images.Image[source]#

Bases: air_sdk.air_model.AirModel

Image model representing a network image.

id#: Unique identifier for the image

name#: Human-readable name of the image

version#: Version of the image

created#: Timestamp when the image was created

creator#: User who created the image

modified#: Timestamp when the image was last modified

mountpoint#: Mountpoint of the image

minimum_resources#: Minimum resources required to run the image

includes_air_agent#: Whether the image includes the Air agent

cpu_arch#: CPU architecture of the image

default_username#: Default username for the image

default_password#: Default password for the image

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

size#: Size of the image

hash#: Hash of the image

is_owned_by_client#: Whether the image is owned by the client

id: str#

name: str#

version: str#

created: datetime.datetime#

creator: str#

modified: datetime.datetime#

mountpoint: str | None#

minimum_resources: MinimumResources#

includes_air_agent: bool#

cpu_arch: str#

default_username: str#

default_password: str#

emulation_type: list[str]#

emulation_version: str#

provider: str#

published: bool#

upload_status: str#

last_uploaded_at: datetime.datetime | None#

size: int#

hash: str#

is_owned_by_client: bool#

classmethod get_model_api() → type[ImageEndpointAPI][source]#: Returns the respective AirModelAPI type for this model.

property 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.

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

Example

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

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).

Returns:

the uploaded image instance

Return type:

Image

Example

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

clear_upload() → Image[source]#

Clear the upload status of the image.

Returns:: the image instance
Return type:: Image

Example

>>> image.clear_upload()

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

Returns:

the published image instance

Return type:

Image

Example

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

unpublish( *, name: str | dataclasses._MISSING_TYPE = ..., version: str | dataclasses._MISSING_TYPE = ..., ) → Image[source]#

Unpublish the image.

Parameters:

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

Returns:

the image instance

Return type:

Image

Example

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

share( *, target_org: str, expires_at: datetime.datetime | dataclasses._MISSING_TYPE = ..., ) → ImageShare[source]#

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

Returns:

The created share instance

Return type:

ImageShare

Example

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

class air_sdk.endpoints.images.ImageEndpointAPI( api: air_sdk.AirApi, default_filters: dict[str, Any] | None = None, )[source]#

Bases: air_sdk.air_model.BaseEndpointAPI[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.

Returns:

The created Image instance

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,
... )

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

Returns:

Iterator of Image instances

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)

get(pk: air_sdk.air_model.PrimaryKey) → Image#

Get a specific image by ID.

Parameters:: pk – The image ID (string or UUID)
Returns:: The Image instance

Example

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

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

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

Example

>>> # File upload
>>> image.upload(filepath='image.qcow2')

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

clear_upload(*, image: Image | air_sdk.air_model.PrimaryKey) → None[source]#

Clear the upload status of the image.

Parameters:: image – image to clear upload
Returns:: None

Example

>>> api.images.clear_upload(image)

publish( *, image: Image | air_sdk.air_model.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 | air_sdk.air_model.PrimaryKey, name: str | dataclasses._MISSING_TYPE = ..., version: str | dataclasses._MISSING_TYPE = ..., ) → Image[source]#

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

Returns:

the unpublished image instance

Return type:

Image

Example

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

share( *, image: Image | air_sdk.air_model.PrimaryKey, target_org: str, expires_at: datetime.datetime | dataclasses._MISSING_TYPE = ..., ) → ImageShare[source]#

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:: The created share object
Return type:: ImageShare

Example

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

claim_image_share( *, image_share: air_sdk.air_model.PrimaryKey, name: str | dataclasses._MISSING_TYPE = ..., version: str | dataclasses._MISSING_TYPE = ..., ) → Image[source]#

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

Returns:

The claimed image

Return type:

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'
... )

property shares: ImageShareEndpointAPI#

Access the image shares API.

Returns:: The API for managing image shares
Return type:: ImageShareEndpointAPI

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( api: air_sdk.AirApi, default_filters: dict[str, Any] | None = None, )[source]#

Bases: air_sdk.air_model.BaseEndpointAPI[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

Returns:

Iterator of ImageShare instances

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)

create( *, image: Image | air_sdk.air_model.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

Returns:

The created image share instance

Return type:

ImageShare

Example

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

get(pk: air_sdk.air_model.PrimaryKey) → ImageShare#

Get a specific shared image by ID.

Parameters:: pk – The image share ID (string or UUID)
Returns:: The ImageShare instance

Example

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

delete(pk: air_sdk.air_model.PrimaryKey) → None#

Delete (unshare) an image share.

Parameters:: pk – The share ID to delete (string or UUID)
Returns:: None

Example

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