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 thedoapi.fetch_image()
anddoapi.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’saction_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 resourceReturn 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, returnNone
.If
wait_time
is exceeded, aWaitTimeoutError
(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 timeoutChanged in version 0.2.0: Name changed from
wait
towait_for_action
Changed in version 0.2.0: Return
self
if there were no actions on the resourceChanged in version 0.2.0: Return
None
if the resource no longer exists afterwardsParameters: - wait_interval (number) – how many seconds to sleep between
requests; defaults to the
doapi
object’swait_interval
if not specified orNone
- 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’swait_time
if not specified orNone
Returns: the resource’s final state
Raises: - DOAPIError – if the API endpoint replies with an error
- WaitTimeoutError – if
wait_time
is exceeded
- wait_interval (number) – how many seconds to sleep between
requests; defaults to the
-
fetch_all_actions
()¶ Returns a generator that yields all of the actions associated with the resource
Return type: generator of Action
sRaises: 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 resourceReturn 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 actionReturn type: Action
orNone
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 stateReturn 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
objectReturn 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 orRegion
object representing the region to which to transfer the imageReturns: an Action
representing the in-progress operation on the imageReturn 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 imageReturn type: Action Raises: DOAPIError – if the API endpoint replies with an error