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"
- 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’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
-
tag
(t)¶ New in version 0.2.0.
Apply the given tag to the resource
Parameters: t (string or Tag
) – the tag to applyReturns: 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 removeReturns: 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
-
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
-
ipv4_address
¶ New in version 0.2.0.
The IP address of the first IPv4 interface listed in the droplet’s
networks
field, orNone
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, orNone
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 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
-
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’sstatus
field to equal the given value. Iflocked
is non-None
,wait
will wait for the droplet’slocked
field to equal (the truth value of) the given value. Exactly one ofstatus
andlocked
must be non-None
.If
wait_time
is exceeded, aWaitTimeoutError
(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 timeoutChanged in version 0.2.0:
locked
parameter addedChanged 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 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.) - locked (
bool
orNone
) – When non-None
, the desired value for thelocked
field of the droplet - 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 droplet has not yet completed, 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: - 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
- status (string or
[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 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
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: -
__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 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