Images

Image

class doapi.Image[source]

An image resource, representing an OS image that can be used to create or reset a droplet.

New images can be created via the Droplet.snapshot() method. They are also automatically created regularly for droplets that have backups enabled. Images can be retrieved with the doapi.fetch_image() and doapi.fetch_all_images() methods, among others.

The DigitalOcean API specifies the following fields for domain objects:

Variables:
  • id (int) – a unique identifier for the image
  • created_at (datetime.datetime) – date & time of the image’s creation
  • distribution (string) – the base Linux distribution used for the image
  • min_disk_size (number) – the minimum disk size (in gigabytes) required for a droplet to use the image
  • name (string) – a human-readable name for the image
  • public (bool) – whether the image is public (i.e., available to all accounts) or not (i.e., only accessible from your account)
  • regions (list of strings) – the slugs of the regions in which the image is available
  • size_gigabytes (number) – the size of the image in gigabytes
  • slug (string or None) – the unique slug identifier for the image (only defined for public images)
  • type (string) – the type of the image: "snapshot" or "backup"
action_url

The endpoint for actions on the individual resource

act(**data)

Perform an arbitrary action on the resource. data will be serialized as JSON and POSTed to the resource’s action_url. All currently-documented actions require the POST body to be a JSON object containing, at a minimum, a "type" field.

Returns:an Action representing the in-progress operation on the resource
Return type:Action
Raises:DOAPIError – if the API endpoint replies with an error
wait_for_action(wait_interval=None, wait_time=None)

Poll the server periodically until the resource’s most recent action has either completed or errored out, and return the resource’s final state afterwards. If no actions have ever been performed on the resource, return self. If the resource no longer exists by the time the action has completed, return None.

If wait_time is exceeded, a WaitTimeoutError (containing the resource’s current state) is raised.

If a KeyboardInterrupt is caught, the resource’s current state is returned immediately without waiting for completion.

Changed in version 0.2.0: Raises WaitTimeoutError on timeout

Changed in version 0.2.0: Name changed from wait to wait_for_action

Changed in version 0.2.0: Return self if there were no actions on the resource

Changed in version 0.2.0: Return None if the resource no longer exists afterwards

Parameters:
  • wait_interval (number) – how many seconds to sleep between requests; defaults to the doapi object’s wait_interval if not specified or None
  • wait_time (number) – the total number of seconds after which the method will raise an error if the action has not yet completed, or a negative number to wait indefinitely; defaults to the doapi object’s wait_time if not specified or None
Returns:

the resource’s final state

Raises:
  • DOAPIError – if the API endpoint replies with an error
  • WaitTimeoutError – if wait_time is exceeded
fetch_all_actions()

Returns a generator that yields all of the actions associated with the resource

Return type:generator of Actions
Raises:DOAPIError – if the API endpoint replies with an error
fetch_last_action()

Fetch the most recent action performed on the resource, or None if no actions have been performed on it yet. If multiple actions were triggered simultaneously, the choice of which to return is undefined.

Changed in version 0.2.0: Return None if there were no actions on the resource

Return type:Action
Raises:DOAPIError – if the API endpoint replies with an error
fetch_current_action()

Fetch the action currently in progress on the resource, or None if there is no such action

Return type:Action or None
Raises:DOAPIError – if the API endpoint replies with an error
__int__()

Convert the resource to its unique integer ID

__str__()[source]

Convert the image to its slug representation. If the image does not have a slug, an AttributeError is raised.

url

The endpoint for general operations on the individual image

fetch()[source]

Fetch & return a new Image object representing the image’s current state

Return type:Image
Raises:DOAPIError – if the API endpoint replies with an error (e.g., if the image no longer exists)
update_image(name)[source]

Update (i.e., rename) the image

Parameters:name (str) – the new name for the image
Returns:an updated Image object
Return type:Image
Raises:DOAPIError – if the API endpoint replies with an error
delete()[source]

Delete the image

Returns:None
Raises:DOAPIError – if the API endpoint replies with an error
transfer(region)[source]

Transfer the image to another region

Parameters:region (string or Region) – the slug or Region object representing the region to which to transfer the image
Returns:an Action representing the in-progress operation on the image
Return type:Action
Raises:DOAPIError – if the API endpoint replies with an error
convert()[source]

Convert the image to a snapshot

Returns:an Action representing the in-progress operation on the image
Return type:Action
Raises:DOAPIError – if the API endpoint replies with an error