Volumes¶

Volume¶

class doapi.Volume[source]¶

New in version 0.3.0.

A block storage volume resource, representing data storage that can be added to a droplet and moved between droplets in the same region.

New volumes are created via the doapi.create_volume() method and can be retrieved with the doapi.fetch_volume() and doapi.fetch_all_volumes() methods.

The DigitalOcean API specifies the following fields for volume objects:

Variables:

id (string) – a unique identifier for the volume
created_at (datetime.datetime) – date & time of the volume’s creation
description (string) – a human-readable free-form description for the volume
droplet_ids (list of integers) – IDs of droplets that the volume is currently attached to
name (string) – a human-readable name for the volume
region (Region) – the region in which the volume is located
size_gigabytes (integer) – the size of the volume in gigabytes

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 `Action`s
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

__str__()[source]¶: Convert the volume object to its ID

url¶: The endpoint for general operations on the individual volume

fetch()[source]¶

Fetch & return a new Volume object representing the volume’s current state

Return type:	Volume
Raises:	DOAPIError – if the API endpoint replies with an error (e.g., if the volume no longer exists)

delete()[source]¶

Delete the volume

Returns:	`None`
Raises:	DOAPIError – if the API endpoint replies with an error

attach(droplet_id)[source]¶

Attach the volume to a droplet

Parameters:	droplet_id (integer or `Droplet`) – the droplet to attach the volume to
Returns:	an `Action` representing the in-progress operation on the volume
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error

detach(droplet_id)[source]¶

Detach the volume from a droplet

Parameters:	droplet_id (integer or `Droplet`) – the droplet from which to remove the volume
Returns:	an `Action` representing the in-progress operation on the volume
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error

resize(size_gigabytes)[source]¶

Resize the volume

Parameters:	size_gigabytes (integer) – the new size of the volume in gigabytes
Returns:	an `Action` representing the in-progress operation on the volume
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error