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"
  • vcpus (int) – number of virtual CPUs
action_url

The endpoint for actions on the specific 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
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. If multiple actions were triggered simultaneously, the choice of which to return is undefined.

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 ID

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

url

The endpoint for operations on the specific 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 Droplets
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 Images
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 Images
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 Kernels
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
upgrade()[source]

Upgrade 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
delete()[source]

Delete the droplet

Returns:None
Raises:DOAPIError – if the API endpoint replies with an error
wait(status=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; otherwise, it will wait for the most recent action on the droplet to finish.

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

Parameters:
Returns:

the droplet’s final state

Return type:

Droplet

Raises:

DOAPIError – if the API endpoint replies with an error

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:
droplet

The Droplet associated with the backup window

fetch_droplet()

Fetch the droplet to which the resource belongs, or return None if the resource’s droplet attribute is None

Return type:Droplet or None
Raises:DOAPIError – if the API endpoint replies with an error

DropletUpgrade

class doapi.DropletUpgrade[source]

A droplet upgrade resource, representing a scheduled upgrade of a droplet.

The set of all currently-scheduled upgrades can be retrieved with the doapi.fetch_all_droplet_upgrades() method.

The DigitalOcean API specifies the following fields for droplet upgrade objects:

Variables:
  • date_of_migration (datetime.datetime) – date & time that the droplet will be migrated
  • droplet_id (int) – the ID of the affected droplet
  • url (string) – the endpoint for operations on the affected droplet
fetch_droplet()[source]

Fetch the droplet affected by the droplet upgrade

Return type:Droplet
Raises:DOAPIError – if the API endpoint replies with an error

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
droplet

The Droplet associated with the kernel

fetch_droplet()

Fetch the droplet to which the resource belongs, or return None if the resource’s droplet attribute is None

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

Convert the resource to its unique 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 NetworkInterfaces) – a list of IPv4 interfaces allocated for a droplet
  • v6 (list of NetworkInterfaces) – a list of IPv6 interfaces allocated for a droplet
droplet

The Droplet associated with the networks resource

fetch_droplet()

Fetch the droplet to which the resource belongs, or return None if the resource’s droplet attribute is None

Return type:Droplet or None
Raises:DOAPIError – if the API endpoint replies with an error

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:
droplet

The Droplet to which the network interface belongs

ip_version

The IP version used by the interface: 4 or 6

fetch_droplet()

Fetch the droplet to which the resource belongs, or return None if the resource’s droplet attribute is None

Return type:Droplet or None
Raises:DOAPIError – if the API endpoint replies with an error
__str__()[source]

Show just the IP address of the interface