air_sdk.endpoints.images

Stub file for images endpoint type hints.

Attributes

Name
`AdvancedMountpoint`

Classes

Name	Description
`MinimumResources`	None
`PlainMountpoint`	A root file system that is a single partition, declared as an object.
`OverlayVolume`	A directory inside a volume, used as an overlay’s upper or work layer.
`OverlayMountpoint`	A root file system assembled from several volumes, which no path names.
`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.PlainMountpoint

Bases: typing.TypedDict

A root file system that is a single partition, declared as an object.

Says what Image.mountpoint says. Use it to declare every image the same way rather than naming some roots as a path and others as an object.

type: Literal[plain]

Always plain

partition: str

Absolute path to the partition hosting the root. A root is a whole filesystem, so this takes no subpath

class air_sdk.endpoints.images.OverlayVolume

Bases: typing.TypedDict

A directory inside a volume, used as an overlay’s upper or work layer.

volume: str

Device holding the directory, in /dev/VG/LV form for a logical volume

subpath: str

Absolute path to the directory within volume

class air_sdk.endpoints.images.OverlayMountpoint

Bases: typing.TypedDict

A root file system assembled from several volumes, which no path names.

schema_version: int

Version of this declaration format

type: Literal[overlay]

Always overlay

lower: list[str]

Read-only volumes forming the base, ordered with the volume closest to the merged view first

upper: OverlayVolume

Writable layer that receives every change

work: OverlayVolume

Scratch directory the overlay requires, on the same volume as upper

AdvancedMountpoint

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.endpoints.history.HistoryModelMixin, 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, for a root that is a single partition named by one path

advanced_mountpoint: AdvancedMountpoint | None

Mountpoint of the image declared as an object, for a root that one path cannot express. Mutually exclusive with mountpoint

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

publicly_published: bool

Whether a published image is publicly accessible

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

notes: str | None

Notes about the image

release_notes: str | None

Release notes for the image

user_manual: str | None

User manual for the image

publish_access_record_id: str | None

UUID of the active publish access record, or None

get_model_api() -> type[ImageEndpointAPI]

model_api: ImageEndpointAPI

update(
    *,
    name: str = ...,
    version: str = ...,
    default_username: str = ...,
    default_password: str = ...,
    mountpoint: str | None = ...,
    advanced_mountpoint: AdvancedMountpoint | None = ...,
    cpu_arch: str = ...,
    includes_air_agent: bool = ...,
    emulation_type: list[str] = ...,
    emulation_version: str = ...,
    provider: str = ...,
    notes: str | None = ...,
    release_notes: str | None = ...,
    user_manual: str | None = ...
) -> 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, for a root that is a single partition named by one path
advanced_mountpoint – Mountpoint of the image declared as an object, for a root that one path cannot express. Mutually exclusive with mountpoint, so pass None for the other when switching
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
notes – Notes about the image
release_notes – Release notes for the image
user_manual – User manual for the image

upload(
    *,
    filepath: str | pathlib.Path,
    timeout: datetime.timedelta | None = ...,
    max_workers: int = ...,
    os_image_manifest: OSImageManifestSpec | None = ...,
    validation_timeout: datetime.timedelta = ...
) -> 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).
os_image_manifest – Optionally create the image’s OS image manifest once the upload completes.
validation_timeout – How long to wait for VALIDATING → COMPLETE before creating the manifest (default: 10 minutes). Only used when os_image_manifest is provided. Independent of timeout.

The API refuses to create a manifest until the image is COMPLETE, so passing os_image_manifest polls the image through VALIDATING first. If the manifest step fails, the uploaded image is kept - fix the payload and retry with api.os_image_manifests.create().

Example:

>>> image.upload(filepath='local_file_path')
>>> image.upload(
...     filepath='cumulus-vx-5.16.qcow2',
...     os_image_manifest=\{
...         'os_type': 'cumulus',
...         'platforms': \{
...             'SN4280': \{
...                 'platform_information_version': '1',
...                 'os_template_version': '1',
...             \}
...         \},
...     \},
... )

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 = ...,
    version: str = ...,
    prefer_public: bool = ...,
    allowed_orgs: list[str] = ...,
    justification: str = ...
) -> Image

Publish the image.

Parameters:

name – new name of the image
version – new version of the image
prefer_public – whether to make the image publicly accessible
allowed_orgs – list of org UUIDs to allowlist when not public
justification – audit text describing the publish reason

Example:

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

Returns:

the published image instance

unpublish(
    *,
    name: str = ...,
    version: str = ...
) -> 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

request_publish(
    *,
    justification: str,
    prefer_public: bool = ...,
    allowed_orgs_request_text: str = ...,
    name: str = ...,
    version: str = ...
) -> Image

Submit a request to publish this image.

Parameters:

justification – Reason for requesting publication
prefer_public – Whether to prefer public access over allowlist
allowed_orgs_request_text – Free-text description of orgs to allowlist
name – New name to apply on publish
version – New version to apply on publish

Returns:

the image instance with updated publish_access_record_id

Example:

>>> image.request_publish(justification='Ready for community use')

request_unpublish(
    *,
    justification: str,
    name: str = ...,
    version: str = ...
) -> Image

Submit a request to unpublish this image.

Parameters:

justification – Reason for requesting unpublication
name – New name to apply on unpublish
version – New version to apply on unpublish

Returns:

the image instance

Example:

>>> image.request_unpublish(justification='No longer maintained')

request_public(
    *,
    prefer_public: bool,
    justification: str
) -> Image

Submit a request to change image visibility to public or restricted.

Parameters:

prefer_public – Whether to make the image publicly accessible
justification – Reason for requesting the visibility change

Returns:

the image instance

Example:

>>> image.request_public(prefer_public=True, justification='Open source')

request_allowlist_change(
    *,
    justification: str,
    allowed_orgs_request_text: str
) -> Image

Submit a request to change the allowlist for this image.

Parameters:

justification – Reason for requesting the allowlist change
allowed_orgs_request_text – Free-text description of orgs to allowlist

Returns:

the image instance

Example:

>>> image.request_allowlist_change(
...     justification='Add partner orgs',
...     allowed_orgs_request_text='org-a, org-b',
... )

cancel_publish_access_record() -> Image

Cancel the active publish access record for this image.

Returns:

the image instance

Example:

>>> image.cancel_publish_access_record()

share(
    *,
    target_org: str,
    expires_at: datetime.datetime = ...
) -> 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

API_CLEAR_UPLOAD_PATH: str

API_PUBLISH_PATH: str

API_UNPUBLISH_PATH: str

API_REQUEST_PUBLISH_PATH: str

API_REQUEST_UNPUBLISH_PATH: str

API_REQUEST_PUBLIC_PATH: str

API_REQUEST_ALLOWLIST_CHANGE_PATH: str

API_CANCEL_PUBLISH_ACCESS_RECORD_PATH: str

API_CLAIM_IMAGE_SHARE_PATH: str

model: type[Image]

create(
    *,
    name: str,
    version: str,
    default_username: str,
    default_password: str,
    mountpoint: str | None = ...,
    advanced_mountpoint: AdvancedMountpoint | None = ...,
    cpu_arch: str = ...,
    includes_air_agent: bool = ...,
    emulation_type: list[str] = ...,
    emulation_version: str = ...,
    provider: str = ...,
    filepath: str | pathlib.Path = ...,
    timeout: datetime.timedelta | None = ...,
    max_workers: int = ...,
    os_image_manifest: OSImageManifestSpec | None = ...,
    validation_timeout: datetime.timedelta = ...
) -> 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, for a root that is a single partition named by one path
advanced_mountpoint – Mountpoint of the image declared as an object, for a root that one path cannot express. Mutually exclusive with mountpoint
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.
os_image_manifest – Optionally create the image’s OS image manifest once the upload completes. Requires filepath, since a manifest may only reference an image that reached COMPLETE.
validation_timeout – How long to wait for VALIDATING → COMPLETE before creating the manifest (default: 10 minutes). Only used when os_image_manifest is provided. Independent of timeout.

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, upload, and attach the OS image manifest in one call
>>> api.images.create(
...     name='cumulus-vx-1.2.3',
...     version='1.0.0',
...     default_username='user',
...     default_password='password',
...     filepath='./cumulus-vx.qcow2',
...     os_image_manifest=\{
...         'os_type': 'cumulus',
...         'platforms': \{
...             'SN4280': \{
...                 'platform_information_version': '1',
...                 'os_template_version': '1',
...             \}
...         \},
...     \},
... )
>>> # 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,
... )

Raises:

ValueError – If os_image_manifest is given without filepath, or carries an image key

list(
    *,
    name: str = ...,
    version: str = ...,
    cpu_arch: Literal[x86, ARM] = ...,
    creator: str = ...,
    includes_air_agent: bool = ...,
    provider: Literal[VM, CONTAINER] = ...,
    published: bool = ...,
    publicly_published: bool = ...,
    upload_status: Literal[READY, UPLOADING, VALIDATING, COMPLETE, PUBLISHING, UNPUBLISHING, COPYING_FROM_IMAGE_SHARE, PENDING_PUBLISH, PENDING_UNPUBLISH] = ...,
    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
publicly_published – Whether a published image is publicly accessible
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 = ...,
    max_workers: int = ...,
    os_image_manifest: OSImageManifestSpec | None = ...,
    validation_timeout: datetime.timedelta = ...
) -> 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.
os_image_manifest – Optionally create the image’s OS image manifest once the upload completes.
validation_timeout – How long to wait for VALIDATING → COMPLETE before creating the manifest (default: 10 minutes). Only used when os_image_manifest is provided. Independent of timeout.

An OS image manifest may only reference an image whose upload_status is COMPLETE, and an image sits in VALIDATING for a while after its parts land. Passing os_image_manifest therefore polls until the image completes before creating the manifest. If that step fails the uploaded image is kept, so fix the payload and retry with api.os_image_manifests.create() rather than re-uploading.

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)
>>> # Upload and attach the OS image manifest in one call
>>> api.images.upload(
...     image='image-uuid',
...     filepath='cumulus-vx-5.16.qcow2',
...     os_image_manifest=\{
...         'os_type': 'cumulus',
...         'platforms': \{
...             'SN4280': \{
...                 'platform_information_version': '1',
...                 'os_template_version': '1',
...             \}
...         \},
...     \},
... )

Raises:

FileNotFoundError – If the file does not exist
ValueError – If filepath is not a regular file, max_workers < 1, or os_image_manifest carries an image key
PermissionError – If the file is not readable
TimeoutError – If os_image_manifest was given and the image did not reach COMPLETE within validation_timeout
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 = ...,
    version: str = ...,
    prefer_public: bool = ...,
    allowed_orgs: List[str] = ...,
    justification: str = ...
) -> Image

Publish the image.

Args:

Required parameters: image: image to publish (Image instance or image ID)

Optional Parameters: name: The name of the image version: The version of the image prefer_public: whether to make the image publicly accessible allowed_orgs: list of org UUIDs to allowlist when not public justification: audit text describing the publish reason

Returns:

Image: the published image instance

Example:

>>> api.images.publish(image=image)

unpublish(
    *,
    image: Image | PrimaryKey,
    name: str = ...,
    version: str = ...
) -> 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

request_publish(
    *,
    image: Image | PrimaryKey,
    justification: str,
    prefer_public: bool = ...,
    allowed_orgs_request_text: str = ...,
    name: str = ...,
    version: str = ...
) -> Image

Submit a request to publish an image.

Args:

Required parameters: image: image to request publication for (Image instance or image ID) justification: Reason for requesting publication

Optional parameters: prefer_public: Whether to prefer public access over allowlist allowed_orgs_request_text: Free-text description of orgs to allowlist name: New name to apply on publish version: New version to apply on publish

Returns:

Image: the image instance with updated publish_access_record_id

Example:

>>> api.images.request_publish(image=image, justification='Ready')

request_unpublish(
    *,
    image: Image | PrimaryKey,
    justification: str,
    name: str = ...,
    version: str = ...
) -> Image

Submit a request to unpublish an image.

Args:

Required parameters: image: image to request unpublication for (Image instance or image ID) justification: Reason for requesting unpublication

Optional parameters: name: New name to apply on unpublish version: New version to apply on unpublish

Returns:

Image: the image instance

Example:

>>> api.images.request_unpublish(image=image, justification='Deprecated')

request_public(
    *,
    image: Image | PrimaryKey,
    prefer_public: bool,
    justification: str
) -> Image

Submit a request to change image visibility to public or restricted.

Args:

Required parameters: image: image to update (Image instance or image ID) prefer_public: Whether to make the image publicly accessible justification: Reason for requesting the visibility change

Returns:

Image: the image instance

Example:

>>> api.images.request_public(image=img, prefer_public=True, justification='')

request_allowlist_change(
    *,
    image: Image | PrimaryKey,
    justification: str,
    allowed_orgs_request_text: str
) -> Image

Submit a request to change the allowlist for an image.

Args:

Required parameters: image: image to update (Image instance or image ID) justification: Reason for requesting the allowlist change allowed_orgs_request_text: Free-text description of orgs to allowlist

Returns:

Image: the image instance

Example:

>>> api.images.request_allowlist_change(
...     image=image,
...     justification='Add partner orgs',
...     allowed_orgs_request_text='org-a, org-b',
... )

cancel_publish_access_record(
    *,
    image: Image | PrimaryKey
) -> Image

Cancel the active publish access record for an image.

Args:

Required parameters: image: image to cancel the record for (Image instance or image ID)

Returns:

Image: the image instance

Example:

>>> api.images.cancel_publish_access_record(image=image)

share(
    *,
    image: Image | PrimaryKey,
    target_org: str,
    expires_at: datetime.datetime = ...
) -> 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 = ...,
    version: str = ...
) -> 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 = ...,
    offset: int = ...,
    ordering: str = ...,
    search: str = ...
) -> 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 = ...
) -> 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