doapi Class

class doapi.doapi(api_token, endpoint='https://api.digitalocean.com', timeout=None, wait_interval=2, wait_time=None, per_page=None)

The primary class for interacting with the DigitalOcean API, used for creating and fetching resources. The resource objects returned by these methods have methods of their own for manipulating them individually.

Parameters:

• api_token (str) – the API token to use for authentication
• endpoint (string) – the URL relative to which requests will be made
• timeout (float, tuple, or None) – the timeout value to use when making requests
• wait_interval (number) – the default number of seconds that “wait” operations will sleep for between requests
• wait_time – the default number of seconds after which “wait” operations will return, or None or a negative number to wait indefinitely
• per_page (integer or None) – the default number of objects that paginate() will fetch on each request, or None to leave unspecified

DEFAULT_ENDPOINT = 'https://api.digitalocean.com'

The official DigitalOcean API endpoint

api_token = None

The API token used for authentication

endpoint = None

The API endpoint URL relative to which requests will be made

timeout = None

The timeout value to use when making requests; see the requests documentation for more information

wait_interval = None

The default number of seconds that wait_droplets(), wait_actions(), and the wait methods of Action, Droplet, FloatingIP, and Image will sleep for between requests

wait_time = None

The default number of seconds after which “wait” operations will return, or None or a negative number to wait indefinitely

per_page = None

The default number of objects that paginate() will fetch on each request, or None to leave unspecified

last_response = None

The requests.Response object returned for the most recent request, or None if no requests have been made yet

last_meta = None

The meta field in the body of the most recent response, or None if there was no such field, no requests have been made yet, or the last response was an error

session = None

The requests.Session object through which all requests are performed

close()

Close the session. All API methods will be unusable after calling this method.

Returns:None

request(url, params=None, data=None, method='GET')

Perform an HTTP request and return the response body as a decoded JSON value

Parameters:

• url (str) – the URL to make the request of. If url begins with a forward slash, endpoint is prepended to it; otherwise, url is treated as an absolute URL.
• params (dict) – parameters to add to the URL’s query string
• data – a value to send in the body of the request. If data is not a string, it will be serialized as JSON before sending; either way, the Content-Type header of the request will be set to application/json. Note that a data value of None means “Don’t send any data”; to send an actual None value, convert it to JSON (i.e., the string "null") first.
• method (str) – the HTTP method to use: "GET", "POST", "PUT", or "DELETE" (case-insensitive); default: "GET"

Returns:

a decoded JSON value, or None if no data was returned

Return type:

list or dict (depending on the request) or None

Raises:

• ValueError – if method is an invalid value
• DOAPIError – if the API endpoint replies with an error

last_rate_limit

A dict of the rate limit information returned in the most recent response, or None if no requests have been made yet. The dict consists of all headers whose names begin with "RateLimit" (case insensitive).

The DigitalOcean API specifies the following rate limit headers:

Variables:

• RateLimit-Limit (string) – the number of requests that can be made per hour
• RateLimit-Remaining (string) – the number of requests remaining until the limit is reached
• RateLimit-Reset (string) – the Unix timestamp for the time when the oldest request will expire from rate limit consideration

paginate(url, key, params=None)

Fetch a sequence of paginated resources from the API endpoint. The initial request to url and all subsequent requests must respond with a JSON object; the field specified by key must be a list, whose elements will be yielded, and the next request will be made to the URL in the .links.pages.next field until the responses no longer contain that field.

Parameters:

• url (str) – the URL to make the initial request of. If url begins with a forward slash, endpoint is prepended to it; otherwise, url is treated as an absolute URL.
• key (str) – the field on each page containing a list of values to yield
• params (dict) – parameters to add to the initial URL’s query string. A "per_page" parameter may be included to override the default per_page setting.

Return type:

generator of decoded JSON values

Raises:

• ValueError – if a response body is not an object or key is not one of its keys
• DOAPIError – if the API endpoint replies with an error

fetch_droplet(obj)

Fetch a droplet by ID number

Parameters:obj (integer, dict, or Droplet) – the ID of the droplet, a dict with an "id" field, or a Droplet object (to re-fetch the same droplet) Return type:Droplet Raises:DOAPIError – if the API endpoint replies with an error

fetch_all_droplets(tag_name=None)

Returns a generator that yields all of the droplets belonging to the account

Changed in version 0.2.0: tag_name parameter added

Parameters:tag_name (string or Tag) – if non-None, only droplets with the given tag are returned Return type:generator of Droplets Raises:DOAPIError – if the API endpoint replies with an error

create_droplet(name, image, size, region, ssh_keys=None, backups=None, ipv6=None, private_networking=None, user_data=None, **kwargs)

Create a new droplet. All fields other than name, image, size, and region are optional and will be omitted from the API request if not specified.

The returned Droplet object will represent the droplet at the moment of creation; the actual droplet may not be active yet and may not have even been assigned an IP address. To wait for the droplet to activate, use the Droplet’s wait() method.

Parameters:

• name (str) – a name for the droplet
• image (integer, string, or Image) – the image ID, slug, or Image object representing the base image to use for the droplet
• size (string or Size) – the slug or Size object representing the size of the new droplet
• region (string or Region) – the slug or Region object representing the region in which to create the droplet
• ssh_keys (iterable) – an iterable of SSH key resource IDs, SSH key fingerprints, and/or SSHKey objects specifying the public keys to add to the new droplet’s /root/.ssh/authorized_keys file
• backups (bool) – whether to enable automatic backups on the new droplet
• ipv6 (bool) – whether to enable IPv6 on the new droplet
• private_networking (bool) – whether to enable private networking for the new droplet
• user_data (str) – a string of user data/metadata for the droplet
• kwargs – additional fields to include in the API request

Returns:

the new droplet resource

Return type:

Droplet

Raises:

DOAPIError – if the API endpoint replies with an error

create_multiple_droplets(names, image, size, region, ssh_keys=None, backups=None, ipv6=None, private_networking=None, user_data=None, **kwargs)

Create multiple new droplets at once with the same image, size, etc., differing only in name. All fields other than names, image, size, and region are optional and will be omitted from the API request if not specified.

The returned Droplet objects will represent the droplets at the moment of creation; the actual droplets may not be active yet and may not have even been assigned IP addresses. To wait for the droplets to activate, use their wait() method or wait_droplets.

Parameters:

• names (list of strings) – the names for the new droplets
• image (integer, string, or Image) – the image ID, slug, or Image object representing the base image to use for the droplets
• size (string or Size) – the slug or Size object representing the size of the new droplets
• region (string or Region) – the slug or Region object representing the region in which to create the droplets
• ssh_keys (iterable) – an iterable of SSH key resource IDs, SSH key fingerprints, and/or SSHKey objects specifying the public keys to add to the new droplets’ /root/.ssh/authorized_keys files
• backups (bool) – whether to enable automatic backups on the new droplets
• ipv6 (bool) – whether to enable IPv6 on the new droplets
• private_networking (bool) – whether to enable private networking for the new droplets
• user_data (str) – a string of user data/metadata for the droplets
• kwargs – additional fields to include in the API request

Returns:

the new droplet resources

Return type:

list of Droplets

Raises:

DOAPIError – if the API endpoint replies with an error

fetch_all_droplet_neighbors()

Returns a generator of all sets of multiple droplets that are running on the same physical hardware

Return type:generator of lists of Droplets Raises:DOAPIError – if the API endpoint replies with an error

wait_droplets(droplets, status=None, locked=None, wait_interval=None, wait_time=None)

Poll the server periodically until all droplets in droplets have reached some final state, yielding each Droplet’s final value when it’s done. If status is non-None, wait_droplets will wait for each droplet’s status field to equal the given value. If locked is non-None, wait_droplets will wait for each 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 any remaining in-progress droplets) is raised.

If a KeyboardInterrupt is caught, any remaining droplets are 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 actions to complete

Parameters:

• droplets (iterable) – an iterable of Droplets and/or other values that are acceptable arguments to fetch_droplet()
• status (string or None) – When non-None, the desired value for the status field of each 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 each Droplet
• wait_interval (number) – how many seconds to sleep between requests; defaults to wait_interval if not specified or None
• wait_time (number) – the total number of seconds after which the method will raise an error if any droplets have not yet completed, or a negative number to wait indefinitely; defaults to wait_time if not specified or None

Return type:

generator of Droplets

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

fetch_action(obj)

Fetch an action by ID number

Parameters:obj (integer, dict, or Action) – the ID of the action, a dict with an "id" field, or an Action object (to re-fetch the same action) Return type:Action Raises:DOAPIError – if the API endpoint replies with an error

fetch_last_action()

Fetch the most recent action performed on the account, or None if no actions have been performed yet. If multiple actions were triggered simultaneously, the choice of which to return is undefined.

Return type:Action or None 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 account

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

wait_actions(actions, wait_interval=None, wait_time=None)

Poll the server periodically until all actions in actions have either completed or errored out, yielding each Action’s final value as it ends.

If wait_time is exceeded, a WaitTimeoutError (containing any remaining in-progress actions) is raised.

If a KeyboardInterrupt is caught, any remaining actions are returned immediately without waiting for completion.

Changed in version 0.2.0: Raises WaitTimeoutError on timeout

Parameters:

• actions (iterable) – an iterable of Actions and/or other values that are acceptable arguments to fetch_action()
• wait_interval (number) – how many seconds to sleep between requests; defaults to wait_interval if not specified or None
• wait_time (number) – the total number of seconds after which the method will raise an error if any actions have not yet completed, or a negative number to wait indefinitely; defaults to wait_time if not specified or None

Return type:

generator of Actions

Raises:

• DOAPIError – if the API endpoint replies with an error
• WaitTimeoutError – if wait_time is exceeded

wait_actions_on_objects(objects, wait_interval=None, wait_time=None)

New in version 0.2.0.

Poll the server periodically until the most recent action on each resource in objects has finished, yielding each resource’s final state when the corresponding action is done.

If wait_time is exceeded, a WaitTimeoutError (containing any remaining in-progress actions) is raised.

If a KeyboardInterrupt is caught, any remaining actions are returned immediately without waiting for completion.

Parameters:

• objects (iterable) – an iterable of resource objects that have fetch_last_action methods
• wait_interval (number) – how many seconds to sleep between requests; defaults to wait_interval if not specified or None
• wait_time (number) – the total number of seconds after which the method will raise an error if any actions have not yet completed, or a negative number to wait indefinitely; defaults to wait_time if not specified or None

Return type:

generator of objects

Raises:

• DOAPIError – if the API endpoint replies with an error
• WaitTimeoutError – if wait_time is exceeded

fetch_ssh_key(obj)

Fetch an SSH public key by ID number or fingerprint

Parameters:obj (integer, string, dict, or SSHKey) – the ID or fingerprint of the SSH key, a dict with an "id" or "fingerprint" field, or an SSHKey object (to re-fetch the same SSH key) Return type:SSHKey Raises:DOAPIError – if the API endpoint replies with an error

fetch_all_ssh_keys()

Returns a generator that yields all of the SSH public keys belonging to the account

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

create_ssh_key(name, public_key, **kwargs)

Add a new SSH public key resource to the account

Parameters:

• name (str) – the name to give the new SSH key resource
• public_key (str) – the text of the public key to register, in the form used by authorized_keys files
• kwargs – additional fields to include in the API request

Returns:

the new SSH key resource

Return type:

SSHKey

Raises:

DOAPIError – if the API endpoint replies with an error

fetch_image(obj)

Fetch an image by ID number

Parameters:obj (integer, dict, or Image) – the ID of the image, a dict with an "id" field, or an Image object (to re-fetch the same image) Return type:Image Raises:DOAPIError – if the API endpoint replies with an error

fetch_image_by_slug(slug)

Fetch an image by its slug

Parameters:slug (str) – the slug of the image to fetch Return type:Image Raises:DOAPIError – if the API endpoint replies with an error

fetch_all_images(type=None, private=None)

Returns a generator that yields all of the images available to the account

Parameters:

• type (string or None) – the type of images to fetch: "distribution", "application", or all (None); default: None
• private (bool) – whether to only return the user’s private images; default: return all images

Return type:

generator of Images

Raises:

DOAPIError – if the API endpoint replies with an error

fetch_all_distribution_images()

Returns a generator that yields all of the distribution images available to the account

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

fetch_all_application_images()

Returns a generator that yields all of the application images available to the account

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

fetch_all_private_images()

Returns a generator that yields all of the user’s private images

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

fetch_all_regions()

Returns a generator that yields all of the regions available to the account

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

fetch_all_sizes()

Returns a generator that yields all of the sizes available to the account

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

fetch_account()

Returns an Account object representing the user’s account

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

fetch_domain(obj)

Fetch a domain by FQDN

Parameters:obj (string, dict, or Domain) – the domain name, a dict with a "name" field, or a Domain object (to re-fetch the same domain) Return type:Domain Raises:DOAPIError – if the API endpoint replies with an error

fetch_all_domains()

Returns a generator that yields all of the domains belonging to the account

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

create_domain(name, ip_address, **kwargs)

Add a new domain name resource to the account.

Note that this method does not actually register a new domain name; it merely configures DigitalOcean’s nameservers to provide DNS resolution for the domain. See How To Set Up a Host Name with DigitalOcean for more information.

Parameters:

• name (str) – the domain name to add
• ip_address (string or FloatingIP) – the IP address to which the domain should point
• kwargs – additional fields to include in the API request

Returns:

the new domain resource

Return type:

Domain

Raises:

DOAPIError – if the API endpoint replies with an error

fetch_floating_ip(obj)

Fetch a floating IP

Parameters:obj (string, integer, dict, or FloatingIP) – an IP address (as a string or 32-bit integer), a dict with an "ip" field, or a FloatingIP object (to re-fetch the same floating IP) Return type:FloatingIP Raises:DOAPIError – if the API endpoint replies with an error

fetch_all_floating_ips()

Returns a generator that yields all of the floating IPs belonging to the account

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

create_floating_ip(droplet_id=None, region=None, **kwargs)

Create a new floating IP assigned to a droplet or reserved to a region. Either droplet_id or region must be specified, but not both.

The returned FloatingIP object will represent the IP at the moment of creation; if the IP address is supposed to be assigned to a droplet, the assignment may not have been completed at the time the object is returned. To wait for the assignment to complete, use the FloatingIP’s wait_for_action() method.

Parameters:

• droplet_id (integer or Droplet) – the droplet to assign the floating IP to as either an ID or a Droplet object
• region (string or Region) – the region to reserve the floating IP to as either a slug or a Region object
• kwargs – additional fields to include in the API request

Returns:

the new floating IP

Return type:

FloatingIP

Raises:

• TypeError – if both droplet_id & region or neither of them are defined
• DOAPIError – if the API endpoint replies with an error

fetch_tag(obj)

New in version 0.2.0.

Fetch a tag by name

Parameters:obj (string, dict, or Tag) – the name of the tag, a dict with a "name" field, or a Tag object (to re-fetch the same tag) Return type:Tag Raises:DOAPIError – if the API endpoint replies with an error

fetch_all_tags()

New in version 0.2.0.

Returns a generator that yields all of the tags belonging to the account

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

create_tag(name)

New in version 0.2.0.

Add a new tag resource to the account

Parameters:name (str) – the name of the new tag Return type:Tag Raises:DOAPIError – if the API endpoint replies with an error