Droplets¶

Droplet¶

class doapi.Droplet[source]¶

A droplet resource, representing a virtual machine provided by DigitalOcean.

New droplets are created via the doapi.create_droplet() and doapi.create_multiple_droplets() methods and can be retrieved with the doapi.fetch_droplet() and doapi.fetch_all_droplets() methods.

The DigitalOcean API specifies the following fields for droplet objects:

Variables:

id (int) – a unique identifier for the droplet
backup_ids (list of integers) – image IDs of backups taken of the droplet
created_at (datetime.datetime) – date & time of the droplet’s creation
disk (number) – size of the droplet’s disk in gigabytes
features (list of strings) – a list of strings naming the features enabled on the droplet
image (Image) – the base image used to create the droplet
kernel (Kernel or None) – the droplet’s current kernel
locked (bool) – whether the droplet is currently locked, preventing actions on it
memory (number) – RAM of the droplet in megabytes
name (string) – a human-readable name for the droplet
networks (Networks) – the network interfaces configured for the droplet
next_backup_window (BackupWindow or None) – the start & end of the next timeframe in which the droplet will be backed up; only defined if backups are enabled on the droplet
region (Region) – the region in which the droplet is located
size (Size) – the current size of the droplet
size_slug (string) – the unique slug identifier for the droplet’s size
snapshot_ids (list of integers) – image IDs of snapshots taken of the droplet
status (string) – the current state of the droplet: "new", "active", "off", or "archive"
tags (list of strings) – tags that have been applied to the droplet
vcpus (int) – number of virtual CPUs

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

__int__()¶: Convert the resource to its unique integer ID

tag(t)¶

New in version 0.2.0.

Apply the given tag to the resource

Parameters:	t (string or `Tag`) – the tag to apply
Returns:	`None`
Raises:	DOAPIError – if the API endpoint replies with an error

untag(t)¶

New in version 0.2.0.

Remove the given tag from the resource

Parameters:	t (string or `Tag`) – the tag to remove
Returns:	`None`
Raises:	DOAPIError – if the API endpoint replies with an error

STATUS_ACTIVE = 'active'¶: The status of droplets that are powered on and operating

STATUS_ARCHIVE = 'archive'¶: The status of “archived” droplets

STATUS_NEW = 'new'¶: The status of recently-created droplets that are not yet usable

STATUS_OFF = 'off'¶: The status of droplets that are powered off

active¶: True iff the droplet’s status is "active"

new¶: True iff the droplet’s status is "new"

off¶: True iff the droplet’s status is "off"

archive¶: True iff the droplet’s status is "archive"

region_slug¶: The unique slug identifier for the droplet’s region

image_slug¶: The unique slug identifier for the droplet’s image, or None if the image doesn’t have a slug

ip_address¶: The IP address of the first interface listed in the droplet’s networks field (ordering IPv4 before IPv6), or None if there are no interfaces

ipv4_address¶: New in version 0.2.0.

The IP address of the first IPv4 interface listed in the droplet’s networks field, or None if there is no IPv4 interface

ipv6_address¶: New in version 0.2.0.

The IP address of the first IPv6 interface listed in the droplet’s networks field, or None if there is no IPv4 interface

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

fetch()[source]¶

Fetch & return a new Droplet object representing the droplet’s current state

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

fetch_all_neighbors()[source]¶

Returns a generator that yields all of the droplets running on the same physical server as the droplet

Return type:	generator of `Droplet`s
Raises:	DOAPIError – if the API endpoint replies with an error

fetch_all_snapshots()[source]¶

Returns a generator that yields all of the snapshot images created from the droplet

Return type:	generator of `Image`s
Raises:	DOAPIError – if the API endpoint replies with an error

fetch_all_backups()[source]¶

Returns a generator that yields all of the backup images created from the droplet

Return type:	generator of `Image`s
Raises:	DOAPIError – if the API endpoint replies with an error

fetch_all_kernels()[source]¶

Returns a generator that yields all of the kernels available to the droplet

Return type:	generator of `Kernel`s
Raises:	DOAPIError – if the API endpoint replies with an error

enable_backups()[source]¶

Enable backups on the droplet

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

disable_backups()[source]¶

Disable backups on the droplet

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

reboot()[source]¶

Reboot the droplet

A reboot action is an attempt to reboot the Droplet in a graceful way, similar to using the reboot command from the console. [APIDocs]

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

power_cycle()[source]¶

Power cycle the droplet

A powercycle action is similar to pushing the reset button on a physical machine, it’s similar to booting from scratch. [APIDocs]

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

shutdown()[source]¶

Shut down the droplet

A shutdown action is an attempt to shutdown the Droplet in a graceful way, similar to using the shutdown command from the console. Since a shutdown command can fail, this action guarantees that the command is issued, not that it succeeds. The preferred way to turn off a Droplet is to attempt a shutdown, with a reasonable timeout, followed by a power off action to ensure the Droplet is off. [APIDocs]

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

power_off()[source]¶

Power off the droplet

A power_off event is a hard shutdown and should only be used if the shutdown() action is not successful. It is similar to cutting the power on a server and could lead to complications. [APIDocs]

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

power_on()[source]¶

Power on the droplet

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

restore(image)[source]¶

Restore the droplet to the specified backup image

A Droplet restoration will rebuild an image using a backup image. The image ID that is passed in must be a backup of the current Droplet instance. The operation will leave any embedded SSH keys intact. [APIDocs]

Parameters:	image (integer, string, or `Image`) – an image ID, an image slug, or an `Image` object representing a backup image of the droplet
Returns:	an `Action` representing the in-progress operation on the droplet
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error

password_reset()[source]¶

Reset the password for the droplet

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

resize(size, disk=None)[source]¶

Resize the droplet

Parameters:	size (string or `Size`) – a size slug or a `Size` object representing the size to resize to disk (bool) – Set to `True` for a permanent resize, including disk changes
Returns:	an `Action` representing the in-progress operation on the droplet
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error

rebuild(image)[source]¶

Rebuild the droplet with the specified image

A rebuild action functions just like a new create. [APIDocs]

Parameters:	image (integer, string, or `Image`) – an image ID, an image slug, or an `Image` object representing the image the droplet should use as a base
Returns:	an `Action` representing the in-progress operation on the droplet
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error

rename(name)[source]¶

Rename the droplet

Parameters:	name (str) – the new name for the droplet
Returns:	an `Action` representing the in-progress operation on the droplet
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error

change_kernel(kernel)[source]¶

Change the droplet’s kernel

Parameters:	kernel (integer or `Kernel`) – a kernel ID or `Kernel` object representing the new kernel
Returns:	an `Action` representing the in-progress operation on the droplet
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error

enable_ipv6()[source]¶

Enable IPv6 networking on the droplet

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

enable_private_networking()[source]¶

Enable private networking on the droplet

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

snapshot(name)[source]¶

Create a snapshot image of the droplet

Parameters:	name (str) – the name for the new snapshot
Returns:	an `Action` representing the in-progress operation on the droplet
Return type:	Action
Raises:	DOAPIError – if the API endpoint replies with an error

delete()[source]¶

Delete the droplet

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

wait(status=None, locked=None, wait_interval=None, wait_time=None)[source]¶

Poll the server periodically until the droplet has reached some final state. If status is non-None, wait will wait for the droplet’s status field to equal the given value. If locked is non-None, wait will wait for the droplet’s locked field to equal (the truth value of) the given value. Exactly one of status and locked must be non-None.

If wait_time is exceeded, a WaitTimeoutError (containing the droplet’s most recently fetched state) is raised.

If a KeyboardInterrupt is caught, the droplet’s most recently fetched state is returned immediately without waiting for completion.

Changed in version 0.2.0: Raises WaitTimeoutError on timeout

Changed in version 0.2.0: locked parameter added

Changed in version 0.2.0: No longer waits for latest action to complete

Parameters:	status (string or `None`) – When non-`None`, the desired value for the `status` field of the droplet, which should be one of `Droplet.STATUS_ACTIVE`, `Droplet.STATUS_ARCHIVE`, `Droplet.STATUS_NEW`, and `Droplet.STATUS_OFF`. (For the sake of forwards-compatibility, any other value is accepted as well.) locked (`bool` or `None`) – When non-`None`, the desired value for the `locked` field of the droplet 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 droplet 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 droplet’s final state
Return type:	Droplet
Raises:	TypeError – if both or neither of `status` & `locked` are defined DOAPIError – if the API endpoint replies with an error WaitTimeoutError – if `wait_time` is exceeded

[APIDocs]

(1, 2, 3, 4, 5, 6) https://developers.digitalocean.com/documentation/v2/

BackupWindow¶

class doapi.BackupWindow[source]¶

A backup window resource, representing an upcoming timeframe in which a droplet is scheduled to be backed up.

A Droplet’s next backup window is stored in its next_backup_window attribute.

The DigitalOcean API implicitly specifies the following fields for backup window objects:

Variables:	start (datetime.datetime) – beginning of the window end (datetime.datetime) – end of the window

Kernel¶

class doapi.Kernel[source]¶

A kernel resource, representing a kernel version that can be installed on a given droplet.

A Droplet’s current kernel is stored in its kernel attribute, and the set of kernels available to a given Droplet can be retrieved with the droplet.fetch_all_kernels() method.

The DigitalOcean API specifies the following fields for kernel objects:

Variables:	id (int) – a unique identifier for the kernel name (string) – a human-readable name for the kernel version (string) – the version string for the kernel

__int__()¶: Convert the resource to its unique integer ID

Networks¶

class doapi.Networks[source]¶

A networks resource, representing a set of network interfaces configured for a specific droplet.

A Droplet’s network information is stored in its networks attribute.

The DigitalOcean API implicitly specifies the following fields for networks objects:

Variables:	v4 (list of `NetworkInterface`s) – a list of IPv4 interfaces allocated for a droplet v6 (list of `NetworkInterface`s) – a list of IPv6 interfaces allocated for a droplet

NetworkInterface¶

class doapi.NetworkInterface[source]¶

A network interface resource, representing an IP address allocated to a specific droplet.

A Droplet’s network interfaces are listed in its networks attribute.

The DigitalOcean API implicitly specifies the following fields for network interface objects:

Variables:	gateway (string) – gateway ip_address (string) – IP address netmask – netmask type – `"public"` or `"private"`

ip_version¶: The IP version used by the interface: 4 or 6

__str__()[source]¶: Show just the IP address of the interface