Immutable Resources

Account

class doapi.Account[source]

An account resource describing the user’s DigitalOcean account.

Current details on the user’s account can be retrieved with the doapi.fetch_account() method.

The DigitalOcean API specifies the following fields for account objects:

Variables:
  • droplet_limit (int) – the maximum number of droplets the account may have at any one time
  • email (string) – the e-mail address the account used to register for DigitalOcean
  • email_verified (bool) – whether the user’s account has been verified via e-mail
  • floating_ip_limit (int) – the maximum number of floating IPs the account may have at any one time
  • status (string) – the status of the account: "active", "warning", or "locked"
  • status_message – a human-readable string describing the status of the account
  • uuid (alphanumeric string) – a UUID for the user
STATUS_ACTIVE = 'active'

The status of an account that is currently active and warning-free

STATUS_WARNING = 'warning'

The status of an account that is currently in a “warning” state, e.g., from having reached the droplet limit

STATUS_LOCKED = 'locked'

The status of a locked account

fetch()[source]

Fetch & return a new Account object representing the account’s current state

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

The endpoint for operations on the user’s account

Action

class doapi.Action[source]

An action resource, representing a change made to another resource.

Actions are created in response to almost all mutating requests on droplets, images, and floating IPs, and they can be retrieved with the doapi.fetch_action(), doapi.fetch_last_action(), doapi.fetch_all_actions() methods as well as the fetch_all_actions, fetch_last_action, and fetch_current_action methods of Droplet, Image, and FloatingIP.

The DigitalOcean API specifies the following fields for action objects:

Variables:
  • id (int) – a unique identifier for the action
  • completed_at (datetime.datetime or None) – date & time of the action’s completion, or None if the action has not completed yet
  • region (Region) – the region in which the action occurred
  • region_slug (string) – the unique slug identifier for the region in which the action occurred
  • resource_id (int) – the unique ID of the resource that the action operated on. If the resource was a droplet or image, this will be its id field. If the resource was a floating IP, this will be the IP address as a 32-bit integer.
  • resource_type (string) – the type of resource that the action operated on: "droplet", "image", or "floating_ip"
  • started_at (datetime.datetime) – date & time of the action’s initiation
  • status (string) – the current status of the action: "in-progress", "completed", or "errored"
  • type (string) – the type of action performed
__int__()

Convert the resource to its unique integer ID

STATUS_IN_PROGRESS = 'in-progress'

The status of actions that are currently still in progress

STATUS_COMPLETED = 'completed'

The status of actions that have completed successfully

STATUS_ERRORED = 'errored'

The status of actions that failed to complete successfully

completed

True iff the action’s status is "completed"

in_progress

True iff the action’s status is "in-progress"

done

True iff the action’s status is not "in-progress"

errored

True iff the action’s status is "errored"

url

The endpoint for general operations on the individual action

fetch()[source]

Fetch & return a new Action object representing the action’s current state

Return type:Action
Raises:DOAPIError – if the API endpoint replies with an error
fetch_resource()[source]

Fetch & return the resource that the action operated on, or None if the resource no longer exists (specifically, if the API returns a 404)

Return type:

Droplet, Image, FloatingIP, or None

Raises:
  • ValueError – if the action has an unknown resource_type (This indicates a deficiency in the library; please report it!)
  • DOAPIError – if the API endpoint replies with a non-404 error
wait(wait_interval=None, wait_time=None)[source]

Poll the server periodically until the action has either completed or errored out and return its final state.

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

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

Changed in version 0.2.0: Raises WaitTimeoutError on timeout

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 action’s final state

Return type:

Action

Raises:
raise_for_error()[source]

New in version 0.2.0.

If the action’s status is "errored", raise an ActionError. Otherwise, do nothing.

Returns:None
Raises:ActionError – if the action’s status is "errored"

Region

class doapi.Region[source]

A region resource, representing a physical datacenter in which droplets can be located.

Available regions can be retreived with the doapi.fetch_all_regions() method.

The DigitalOcean API specifies the following fields for region objects:

Variables:
  • available (bool) – whether new droplets can be created in the region
  • features (list of strings) – a list of strings naming the features available in the region
  • name (string) – a human-readable name for the region
  • sizes (list of strings) – the slugs of the sizes available in the region
  • slug (string) – the unique slug identifier for the region
__str__()[source]

Convert the region to its slug representation

Size

class doapi.Size[source]

A size resource, representing an option for the amount of RAM, disk space, etc. provisioned for a droplet.

Available sizes can be retreived with the doapi.fetch_all_sizes() method.

The DigitalOcean API specifies the following fields for size objects:

Variables:
  • available (bool) – whether new droplets can be created with this size
  • disk (number) – disk size of a droplet of this size in gigabytes
  • memory (number) – RAM of a droplet of this size in megabytes
  • price_hourly (number) – the hourly cost for a droplet of this size in USD
  • price_monthly (number) – the monthly cost for a droplet of this size in USD
  • regions (list of strings) – the slugs of the regions in which this size is available
  • slug (string) – the unique slug identifier for the size
  • transfer (number) – the amount of transfer bandwidth in terabytes available for a droplet of this size
  • vcpus (int) – the number of virtual CPUs on a droplet of this size
__str__()[source]

Convert the size to its slug representation