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()
anddoapi.create_multiple_droplets()
methods and can be retrieved with thedoapi.fetch_droplet()
anddoapi.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
orNone
) – 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
orNone
) – 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’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
-
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. 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 actionReturn type: Action
orNone
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
-
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), orNone
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 stateReturn 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
sRaises: 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
sRaises: 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
sRaises: 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
sRaises: 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 dropletReturn 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 dropletReturn 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 dropletReturn 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 dropletReturn 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 ashutdown
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 dropletReturn type: Action Raises: DOAPIError – if the API endpoint replies with an error
-
power_off
()[source]¶ Power off the droplet
Apower_off
event is a hard shutdown and should only be used if theshutdown()
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 dropletReturn 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 dropletReturn 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 anImage
object representing a backup image of the dropletReturns: an Action
representing the in-progress operation on the dropletReturn 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 dropletReturn type: Action Raises: DOAPIError – if the API endpoint replies with an error
-
resize
(size, disk=None)[source]¶ Resize the droplet
Parameters: Returns: an
Action
representing the in-progress operation on the dropletReturn type: 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 anImage
object representing the image the droplet should use as a baseReturns: an Action
representing the in-progress operation on the dropletReturn 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 dropletReturn 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 orKernel
object representing the new kernelReturns: an Action
representing the in-progress operation on the dropletReturn 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 dropletReturn 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 dropletReturn 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 dropletReturn 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 dropletReturn 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’sstatus
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 aKeyboardInterrupt
is caught, the droplet’s most recently fetched state is returned immediately without waiting for completion.Parameters: - status (string or
None
) – When non-None
, the desired value for thestatus
field of the droplet, which should be one ofDroplet.STATUS_ACTIVE
,Droplet.STATUS_ARCHIVE
,Droplet.STATUS_NEW
, andDroplet.STATUS_OFF
. (For the sake of forwards-compatibility, any other value is accepted as well.) - 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 return, or a negative number to wait indefinitely;
defaults to the
doapi
object’swait_time
if not specified orNone
Returns: the droplet’s final state
Return type: Raises: DOAPIError – if the API endpoint replies with an error
- status (string or
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 itsnext_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
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
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 itskernel
attribute, and the set of kernels available to a givenDroplet
can be retrieved with thedroplet.fetch_all_kernels()
method.The DigitalOcean API specifies the following fields for kernel objects:
Variables: -
fetch_droplet
()¶ Fetch the droplet to which the resource belongs, or return
None
if the resource’sdroplet
attribute isNone
Return type: Droplet
orNone
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 itsnetworks
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
- v4 (list of
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 itsnetworks
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
or6