API Reference¶

resource¶

exception dopyapi.resource.ClientError¶: This exception is raised when the client sends a wrong request

exception dopyapi.resource.ClientForbiddenError¶: This exception is raised when the client is forbidden from accessing Digital Ocean.

exception dopyapi.resource.DOError¶: This exception is raised when an error happens in Digital Ocean side.

class dopyapi.resource.Resource(resource)¶

The base class for all managed Digital Ocean resources

In this class we have methods to make API requests using HTTP verbs (GET, POST, DELETE, HEAD and PUT) which are documented in Digital Ocean API documentation, we also use python magic methods to manage instance attributes of managed resources.

auth¶

An authentication object which holds the used access token and base URL for all API calls.

Type:	auth.Auth

resource¶

This attribute holds the class of the managed resource, this class must extend Resource class and define these class attributes:

_url: The API endpoint used to manage the resource.

_single: The dictionary index used when fetching single instances.

_plural: The dictionary index used when fetching multiple instances.

_fetch_attrs: A list of attributes that can be used to fetch single instances.

_static_attrs: A list of attributes set by DO API and cannot be changed directly.

_dynamic_attrs: A list of attributes that can be changed and saved or used when creating new instances.

_action_attrs: A list of actions that can be used on this resource.

_delete_attr: An attribute used when deleting instances.

_update_attr: An attribute used when updating instances.

_action_attr: An attribute used when calling actions.

_id_attr: The attribute that hold a unique identifier for the resource.

_resource_type: The type of resource as a string

Type:	type

action(**kwargs)¶

Call an action based on the action_attr and passed arguments

Parameters:	url (str) – The url used to call the action, if None then the resource’s action attribute is used. default None tag_name (str) – The name of tag to use as a query string. default None type (str) – The type of action called.
Returns:	The action just created.
Return type:	Action
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

create(**kwargs)¶

This method is used to create a new instance based on arguments.

Returns:	JSON object from the API
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

delete(**kwargs)¶

Send a DELETE request to Digital Ocean API

Parameters:	url (str) – The URL used when sending the request to the API data (str) – The data to send with the request this is optional and it defaults to None.
Returns:	A dictionary with one key “status” and value “deleted” if status code is 204 or 404
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

get(url, **kwargs)¶

Send a GET request to Digital Ocean API

Parameters:	url (str) – The URL to fetch from the API
Returns:	The dictionary response from the API if status code is 200.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

getAction(action_id)¶

This method is used to fetch a single action based on its ID.

Parameters:	action_id (int) – The ID of action to fetch.
Returns:	The action object with the used ID.
Return type:	Action
Raises:	`ClientError` – This is raised if this resource does not support actions or the status code is 400 or 422. `DOError` – This is raised when the status code is 500 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

getID()¶: Return the ID value for the instance.

json()¶

Return a dictionary of all Digital Ocean attributes for the resource

Returns:	A dictionary of key/value pairs for the object’s attributes.
Return type:	dict

classmethod list(*args, **kwargs)¶

This method is used to fetch multiple instances from the API.

Parameters:	url (str) – The URL used for fetching, it defaults to the defined URL for the resource. page (int) – The number of page in results to fetch default is 1 per_page (int) – The number of instances in a single page default is 20
Returns:	A list of dictionaries from Digital Ocean API.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listActions(**kwargs)¶

This method is used to list all actions for this instance

Returns:	A list of action objects
Return type:	list
Raises:	`ClientError` – This is raised if this resource does not support actions or the status code is 400 or 422. `DOError` – This is raised when the status code is 500 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

load()¶

This method is used to force loading the attributes from the API.

Returns:	The value for ID attribute.

post(url, data, **kwargs)¶

Send a POST request to Digital Ocean API

Parameters:	url (str) – The URL used when sending the request to the API
Returns:	The dictionary response from the API if status code is 201 or 202.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

put(url, data, **kwargs)¶

Send a PUT request to Digital Ocean API

Parameters:	url (str) – The URL used when sending the request to the API
Returns:	The dictionary response from the API if status code is 204, if the status code is 202 it is {“status”: “success”}
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

save(url=None)¶

Update the instance with all values for dynamic attributes

This method calls PUT on the URL for updating the instance, it passes all values for dynamic attributes to prevent any loss of any value for any attribute.

Parameters:	url (str) – The url used to send the update request, if it is None then the default URL for the resource is used. default None
Returns:	The dictionary response from the API if status code is 204.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

exception dopyapi.resource.ResourceNotFoundError¶: This exception is raised when we try to access a URL that does not exist.

1-Click Applications¶

class dopyapi.clickapps.ClickApp(data=None)¶

This class represents 1-Click applications in Digital Ocean.

These are pre-built Droplet images and kubernetes apps already setup for you.

slug¶

The slug identifier for the 1-Click application.

Type:	str

type¶

The type of the 1-Click application, it could be either ‘droplet’ or ‘kubernetes’ only so far.

Type:	str

classmethod list(type=None)¶

This method returns a list of Click Apps as defined by its arguments

Parameters:	type (str) – The type of Click Apps to list, if None it fetches all click apps. default None
Returns:	A list of Click Apps
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listDroplet()¶

This method returns a list of Click Apps of type “droplet”

Returns:	A list of Click Apps of type droplet only
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listKubernetes()¶

This method returns a list of Click Apps of type kubernetes

Returns:	A list of Click Apps of type kubernetes
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

account¶

class dopyapi.account.Account¶

Get general information about your account

This class is used to retrieve information about the user’s account, these information are saved as instance attributes described below

email¶

The email of the user

Type:	str

uuid¶

A universal unique ID for the user

Type:	str

droplet_limit¶

The maximum number of droplets this user can create

Type:	int

floating_ip_limit¶

The maximum number of floating IPs this user can create

Type:	int

email_verified¶

This checks if the user has verified their email address

Type:	bool

status¶

The status of user acount

Type:	str

status_message¶

A string that describes the status of user account

Type:	str

actions¶

class dopyapi.actions.Action(data=None)¶

A class used to manage actions in DigitalOcean.

This is a general class that can used with all types of actions it is used when getting information about actions.

id¶

A unique identifier for the action

Type:	int

status¶

The status of the action it could be “in-progress”, “completed” and “errored”

Type:	str

type¶

The type of action, for example “transfer” to represent the state of image transfer action.

Type:	str

started_at¶

The time when the action started

Type:	datetime

completed_at¶

The time when the action was completed.

Type:	datetime

resource_id¶

The unique identifier for the resource associated with this action

Type:	int

resource_type¶

The type of resource associated with this action

Type:	str

region¶

The region where the action occured.

Type:	Region

region_slug¶

The region slug where the action occured.

Type:	str

classmethod list(**kwargs)¶

Used to get a list of all actions

Parameters:	per_page (int) – The number of actions returned in a single page result (defaults to 20) page (int) – The page to be fetched from DigitalOcean (defaults to 1)
Returns:	A list of actions objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

auth¶

class dopyapi.auth.Auth(token=None, base_url='https://api.digitalocean.com/v2')¶

This class holds authentication information

Here we store the authentication information needed by other classes to access and authenticate to Digital Ocean API, these information are stored in attributes as shown below

token¶

The authentication token for the Digital Ocean API.

Type:	str

base_url¶

The base URL used for all API calls. Defaults (https://api.digitalocean.com/v2)

Type:	str

Raises:	`AuthenticationNeeded` – This is raised in case no token is provided and it cannot be found in “DO_TOKEN” environment variable.

exception dopyapi.auth.AuthenticationNeeded¶: This exception is raised when no authentication data is provided.

dopyapi.auth.authenticate(token=None, base_url='https://api.digitalocean.com/v2')¶

Store authentication information for the Resource class

The Resource class is base for all Digital Ocean resources, this function creates a new authentication object from the data provided in arguments and assigns it to the Resource class as class attribute

Parameters:	token (str) – The token used to authenticate to Digital Ocean API. defaults (None) base_url (str) – The URL used for all API calls. defaults (https://api.digitalocean.com/v2)
Raises:	`AuthenticationNeeded` – This is raised in case no token is provided and it cannot be found in “DO_TOKEN” environment variable.

bills¶

class dopyapi.bills.Balance¶

This class holds information about customer’s balance

month_to_date_balance¶

Balance as of the generated_at time. This value includes the account_balance and month_to_date_usage.

Type:	str

account_balance¶

Current balance of the customer’s most recent billing activity. Does not reflect month_to_date_usage.

Type:	str

month_to_date_usage¶

Amount used in the current billing period as of the generated_at time.

Type:	str

generated_at¶

The time at which balances were most recently generated.

Type:	datetime.datetime

class dopyapi.bills.BillingHistory(data=None)¶

This class can be used to retrieve the billing history for customers

description¶

Description of the billing history entry.

Type:	str

ammount¶

Amount of the billing history entry.

Type:	str

invoice_id¶

ID of the invoice associated with the billing history entry, if applicable.

Type:	str

invoice_uuid¶

UUID of the invoice associated with the billing history entry, if applicable.

Type:	str

date¶

Time the billing history entry occured.

Type:	datetime.datetime

type¶

Type of billing history entry.

Type:	str

classmethod list(**kwargs)¶

This method returns a list of billing history as defined by its arguments

Parameters:	page (int) – The page to fetch from all history (defaults 1) per_page (int) – The number of items per a single page (defaults 20)
Returns:	A list of billing history
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

CDNs¶

class dopyapi.cdns.CDN(data=None)¶

This class represents CDN endpoints in Digital Ocean

Here we can create, list, update and delete CDN Endpoints which are used to serve static content from Digital Ocean Spaces to users all around the world.

id¶

A unique ID that can be used to identify and reference a CDN endpoint.

Type:	str

origin¶

The fully qualified domain name (FQDN) for the origin server which provides the content for the CDN. This is currently restricted to a Space.

Type:	str

endpoint¶

The fully qualified domain name (FQDN) from which the CDN-backed content is served.

Type:	str

created_at¶

The time when the CDN Endpoint was created.

Type:	str

ttl¶

The amount of time the content is cached by the CDN’s edge servers in seconds.

Type:	int

certificate_id¶

The ID of a DigitalOcean managed TLS certificate used for SSL when a custom subdomain is provided.

Type:	str

custom_domain¶

The fully qualified domain name (FQDN) of the custom subdomain used with the CDN Endpoint.

Type:	str

classmethod list(**kwargs)¶

This method returns a list of CDN Endpoints as defined by its arguments

Parameters:	page (int) – The page to fetch from all CDN Endpoints (defaults 1) per_page (int) – The number of CDN Endpoints per a single page (defaults 20)
Returns:	A list of CDN Endpoints
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

Certificates¶

class dopyapi.certificates.Certificate(data=None)¶

This class represents a single certificate in Digital Ocean.

Certificates can be either, custom (created, uploaded and renewed by the user) or managed (Uses let’ encrypt free certificates and managed by Digital Ocean entrirely).

id¶

A unique ID that can be used to identify and reference a certificate.

Type:	str

name¶

A unique human-readable name referring to a certificate.

Type:	str

not_after¶

A time value given in ISO8601 combined date and time format that represents the certificate’s expiration date.

Type:	datetime.datetime

sha1_fingerprint¶

A unique identifier generated from the SHA-1 fingerprint of the certificate.

Type:	str

created_at¶

A time value given in ISO8601 combined date and time format that represents when the certificate was created.

Type:	datetime.datetime

dns_names¶

An array of fully qualified domain names (FQDNs) for which the certificate was issued.

Type:	list

state¶

A string representing the current state of the certificate. It may be “pending”, “verified”, or “error”.

Type:	str

type¶

A string representing the type of the certificate. The value will be “custom” for a user-uploaded certificate or “lets_encrypt” for one automatically generated with Let’s Encrypt.

Type:	str

create(name, type='lets_encrypt', private_key=None, leaf_certificate=None, certificate_chain=None, dns_names=[])¶

Create a new SSL certificate

We need to pass the name of certificate and some other values according to its type, if type is ‘lets_encrypt’ you need to use dns_names or if the type is ‘custom’ you need to use private_key, leaf_certificate and certificate_chain.

Parameters:	name (str) – The name of certificate. type (str) – The type of certificate, it could be either ‘lets_encrypt’ or ‘custom’, default is ‘lets_encrypt’ private_key (str) – The private key for certificate, required when creating a custom certificate. default is None leaf_certificate (str) – The contents of a PEM-formatted public SSL certificate. required with custom certificates. default is None certificate_chain (str) – The full PEM-formatted trust chain between the certificate authority’s certificate and your domain’s SSL certificate. required with custom certificates. default is None. dns_names (list) – A list of fully qualified domain names (FQDNs) for which the certificate will be issued. The domains must be managed using DigitalOcean’s DNS. required for lets_encrypt certificates. default is []
Returns:	JSON object from the API
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. or when reqired attributes use default values, based on certificate type. `ClientForbiddenError` – This is raised when the domain is not managed in Digital Ocean. `ResourceNotFoundError` – This is raised when the status code is 404

classmethod list(**kwargs)¶

This method returns a list of certificates as defined by its arguments

Parameters:	page (int) – The page to fetch from all certificates (defaults 1) per_page (int) – The number of certificates per a single page (defaults 20)
Returns:	A list of certificates
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

Container Registry¶

class dopyapi.registry.DockerCredentials(cred)¶

This class is used to store docker credentials for a docker registry in Digital Ocean.

apply(file_name='/home/docs/.docker/config.json')¶

Use this function to save the docker credentials to your docker configuration file

Parameters:	file_name (str) – The name of the file that contains docker credentials default value is `$HOME/.docker/config.json`

class dopyapi.registry.Registry(data=None)¶

This class represents the container registry in your account.

name¶

The name of the container registry to validate.

Type:	str

delete()¶

Send a DELETE request to Digital Ocean API

Parameters:	url (str) – The URL used when sending the request to the API data (str) – The data to send with the request this is optional and it defaults to None.
Returns:	A dictionary with one key “status” and value “deleted” if status code is 204 or 404
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

getDockerCredentials(read_write=False, expiry_seconds=None)¶

Get the docker credentials for this registry.

Returns:	An object that contains the docker credentials.
Return type:	DockerCredentials
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

validate(name)¶

Make sure the passed name is a valid name for docker registry and can be used here.

Parameters:	name (str) – The name to validate.
Returns:	True if name is valid and False otherwise
Return type:	bool

class dopyapi.registry.Repository(registry_name, data=None)¶

This class represents the container Repository in your registry.

registry_name¶

The name of the container registry.

Type:	str

name¶

The name of the repository.

Type:	str

latest_tag¶

The latest tag of the repository.

Type:	RepositoryTag

tag_count¶

The number of tags in the repository.

Type:	int

classmethod list(registry_name, **kwargs)¶

Return a list of repositories based on arguments

Parameters:	registry_name (str) – The name of the Container Registry page (int) – The page to fetch (defaults 1) per_page (int) – The number of repositories in the page (defaults 20)
Returns:	A list of repository objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listTags(**kwargs)¶

Return a list of repositoriy tags based on arguments

Parameters:	page (int) – The page to fetch (defaults 1) per_page (int) – The number of repository tags in the page (defaults 20)
Returns:	A list of repository tag objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

class dopyapi.registry.RepositoryTag(registry_name, repository_name, data=None)¶

This class represents a single tgged repository image in your registry.

registry_name¶

The name of the container registry.

Type:	str

repository¶

The name of the repository.

Type:	str

tag¶

The name of the tag.

Type:	str

manifest_digest¶

The digest of the manifest associated with the tag.

Type:	str

compressed_size_bytes¶

The compressed size of the tag in bytes.

Type:	int

size_bytes¶

The uncompressed size of the tag in bytes (this size is calculated asynchronously so it may not be immediately available).

Type:	int

updated_at¶

The time the tag was last updated.

Type:	datetime

deleteByDigest()¶: Delete current repository tag using its manifest digest value.

Databases¶

class dopyapi.databases.DatabaseBackup(created_at, size_gigabytes)¶

This class represents a database cluster backup.

size_gigabytes¶

The size of the database backup in GBs.

Type:	float

created_at¶

A time value given in ISO8601 combined date and time format at which the backup was created.

Type:	datetime.datetime

class dopyapi.databases.DatabaseCluster(data=None)¶

This class represents a single database cluster in Digital Ocean.

The database cluster simplifies database management, it offers these kinds of clusters “PostgreSQL”, “MySQL” and “Redis”.

id¶

A unique ID that can be used to identify and reference a database cluster.

Type:	str

name¶

A unique, human-readable name referring to a database cluster.

Type:	str

engine¶

A slug representing the database engine used for the cluster. The possible values are: “pg” for PostgreSQL, “mysql” for MySQL, and “redis” for Redis.

Type:	str

version¶

A string representing the version of the database engine to use for the cluster. If excluded, the specified engine’s default version is used. The available versions for PostgreSQL are “10” and “11” defaulting to the later. For MySQL, the only available version is “8”. For Redis, the only available version is “5”.

Type:	str

connection¶

An object containing the information required to connect to the database (see below).

Type:	DatabaseConnection

private_connection¶

An object containing the information required to connect to the database via the private network (see below).

Type:	DatabaseConnection

users¶

A list containing objects describing the database’s users (see below).

Type:	list

db_names¶

A list of strings containing the names of databases created in the database cluster.

Type:	list

num_nodes¶

The number of nodes in the database cluster.

Type:	int

size¶

The slug identifier representing the size of the nodes in the database cluster.

Type:	str

region¶

The slug identifier for the region where the database cluster is located.

Type:	str

status¶

A string representing the current status of the database cluster. Possible values include creating, online, resizing, and migrating.

Type:	str

maintenance_window¶

An object containing information about any pending maintenance for the database cluster and when it will occur (see below). The used keys for the maintenance windo object are:

day (str): The day of the week on which to apply maintenance updates (e.g. “saturday”).

hour (str): The hour in UTC at which maintenance updates will be applied in 24 hour format (e.g. “00:22:00”).

pending (bool): A boolean value indicating whether any maintenance is scheduled to be performed in the next window.

description (list): A list of strings, each containing information about a pending maintenance update.

Type:	dict

created_at¶

A time value given in ISO8601 combined date and time format that represents when the database cluster was created.

Type:	datetime

tags¶

A list of tags that have been applied to the database cluster.

Type:	list

private_network_uuid¶

A string specifying the UUID of the VPC to which the database cluster is assigned.

Type:	str

Connection and Private Connection

These two dictionaries hold keys and values for connection information, used keys are:

uri (str): A connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.

database (str): The name of the default database.

host (str): The FQDN pointing to the database cluster’s current primary node.

port (int): The port on which the database cluster is listening.

user (str): The default user for the database.

password (str): The randomly generated password for the default user.

ssl (bool): A boolean value indicating if the connection should be made over SSL.

addDB(name)¶

Create a new Database in the cluster.

Parameters:	name (str) – The name of new database
Returns:	The dictionary response from the API.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429 or if the database cluster type is ‘redis’ `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

addPool(**kwargs)¶

Add a new connection pool to the database cluster if its type is PostgreSQL

You can pass individual pool attributes here or use a DatabaseConnectionPool object.

addUser(name, auth_plugin='caching_sha2_password')¶

Add a new user to the database cluster.

Parameters:	name (str) – The name to give the database user. auth_plugin (str) – A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are “mysql_native_password” or “caching_sha2_password”. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is “caching_sha2_password.” default caching_sha2_password
Returns:	The dictionary response from the API.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429, or the database cluster is of type ‘redis’ or if authentication plugin is neither ‘caching_sha2_password’ nor ‘mysql_native_password’. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

createReplica()¶

Create a new read only replica.

Parameters:

name (str) – The name to give the read-only replica.
region (Region) – A slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster.
size (str) – A slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating.
tags (list) – A flat list of tag names as strings to apply to the read-only replica after it is created. Tag names can either be existing or new tags.
private_network_uuid (str) – A string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account’s default VPC for the region.

deleteDB(name)¶

Delete a database from the cluster.

Parameters:	name (str) – The name of database to delete.
Returns:	A dictionary with one key “status” and value “deleted”.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster type is ‘redis’. `ClientForbiddenError` – This is raised when the status code is 403

deletePool(name)¶

Delete a Connection Pool from the cluster.

Parameters:	name (str) – The name of the connection pool to delete.
Returns:	A dictionary with one key “status” and value “deleted”.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster type is not ‘PostgreSQL’. `ClientForbiddenError` – This is raised when the status code is 403

deleteReplica(name)¶

Delete a read only replica by its name.

This method can only be called for mysql and pg clusters. :param name: The name of replica to delete. :type name: str

Returns:	A dictionary with one key “status” and value “deleted” if status code is 204 or 404
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or when the database cluster engine is redis `ClientForbiddenError` – This is raised when the status code is 403

deleteUser(name)¶

Delete a database user by name.

Parameters:	name (str) – The name of database user to delete.
Returns:	A dictionary with one key “status” and value “deleted”.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or when the cluster type is ‘redis’ `ClientForbiddenError` – This is raised when the status code is 403

getDB(name)¶

Retrieve the database from the cluster.

Parameters:	name (str) – The name of database to retrieve.
Returns:	The dictionary response from the API if status code is 200.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster type is ‘redis’. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

getEvPolicy()¶

Retrieve the configured eviction policy for an existing Redis cluster.

Returns:	The configured eviction policy.
Return type:	str
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster type is not ‘Redis’. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

getPool(name)¶

Retrieve a connection pool from the cluster.

Parameters:	name (str) – The name of the connection pool to retrieve.
Returns:	The connection pool object.
Return type:	`DatabaseConnectionPool`
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster type is not ‘PostgreSQL’. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

getReplica(name)¶

Return a read only replica by its name.

This method can only be called with mysql and pg clusters

Parameters:	name (str) – The name of read only replica
Returns:	The dictionary response from the API, this dictionary has attributes for ready only replicas.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or when the database cluster engine is redis `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

getSqlMode()¶

Retrieve the configured SQL mode for mysql cluster.

Returns:	A string specifying the configured SQL modes for the MySQL cluster.
Return type:	str
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster type is not ‘mysql’. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

getUser(name)¶

Retrieve information for the database user by name.

Parameters:	name (str) – The name of database user to retrieve.
Returns:	An object representing the retrieved user.
Return type:	`DatabaseUser`
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or database cluster type is ‘redis’ `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod list(**kwargs)¶

This method returns a list of databases as defined by its arguments

Parameters:	page (int) – The page to fetch from all databases (defaults 1) per_page (int) – The number of databases per a single page (defaults 20)
Returns:	A list of databases
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listBackups()¶

List database backups for the cluster.

If the cluster is of type ‘redis’, this will throw ClientError exception, otherwise it will return a list of DatabaseBackup objects.

Returns:	A list of `DatabaseBackup` objects.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422, or the database cluster type is ‘redis’ `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listDBS()¶

List all databases in the cluster.

Returns:	A list of dictionaries as returned from the API.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster type is ‘redis’. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listFirewall()¶

Return a list of all Firewall rules for the cluster.

Returns:	A list of :class::~dopyapi.databases.DatabaseFirewall objects.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or when the database cluster engine is redis `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listPools()¶

List all connection pools in the cluster.

Returns:	A list of `DatabaseConnectionPool` objects.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster type is not ‘PostgreSQL’. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listReplicas()¶

Return a list of all read only replicas.

This method can only be called with mysql and pg clusters

Returns:	A list of read only replica dictionaries, each dictionary has attributes for ready only replicas.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or when the database cluster engine is redis `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listUsers()¶

List all database cluster users.

Returns:	A list of `DatabaseUser` objects.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or database cluster type is ‘redis’ `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

migrate(region)¶

Migrate the database cluster to a new region.

Parameters:	region (str) – The region to migrate to.
Returns:	The dictionary response from the API if status code is 204, if the status code is 202 it is {“status”: “success”}
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

replicate(name, size, region=None, tags=[], private_network_uuid=None)¶

Replicate the current database cluster to another one, with a different name and size.

If we do not specify a new region then the same region will be used for the database cluster.

Parameters:	name (str) – The name of the new cluster. size (Size) – The size of new cluster. region (Region) – The region for new cluster, default None. tags (list) – A list of tags for new cluster, default [] private_network_uuid (str) – The UUID of private network for new cluster default is None
Returns:	The dictionary response from the API.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429, or if the cluster type is redis. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

resetAuth(name, auth_plugin)¶

Change authentication plugin for the database user.

This is only available for mysql clusters.

Parameters:	name (str) – The name of database user. auth_plugin (str) – The authentication plugin it could be either ‘mysql_native_password’ or ‘caching_sha2_password’
Returns:	The dictionary response from the API.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429, or the database cluster type is not ‘mysql’ or the authentication plugin is neither ‘caching_sha2_password’ nor ‘mysql_native_password’. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

resize(size, num_nodes)¶

Change the size of the database cluster.

Parameters:	size (str) – The new size of the cluster num_nodes (int) – The new number of nodes
Returns:	The dictionary response from the API.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

setEvPolicy(policy)¶

Set the eviction policy for redis clusters

Parameters:	policy (str) – A string specifying the desired eviction policy for the Redis cluster. Valid vaules are: noeviction, allkeys_lru, allkeys_random, volatile_lru, volatile_random, or volatile_ttl.
Returns:	It returns this dictionary {“status”: “success”}
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster’s type is not redis. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

setMaintenanceWindow(day, hour)¶

Set the maintenance window for the database cluster.

Here you need to setup two values, one for the day of the week and the other is for the hour.

Parameters:	day (str) – The day of week for maintenance, for example: ‘friday’ hour (str) – The hour of maintenance, for example 23:55
Returns:	The dictionary response from the API.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

setSqlMode(mode='ANSI, ERROR_FOR_DIVISION_BY_ZERO, NO_ENGINE_SUBSTITUTION, NO_ZERO_DATE, NO_ZERO_IN_DATE, STRICT_ALL_TABLES')¶

Set SQL Mode for mysql clusters

Parameters:	mode (str) – A single string specifying the desired SQL modes for the MySQL cluster separated by commas. default is “ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES”
Returns:	It returns this dictionary {“status”: “success”}
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or if the database cluster’s type is not mysql. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

updateFirewall(rules)¶

Add a new firewall rule to the database cluster.

Here we can pass a list of rules or a single rule that will be added to the cluster.

Parameters:	rules (list \| DatabaseFirewall) – A list of rules to add.
Returns:	The dictionary response from the API.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

waitReady()¶: Wait untill the cluster is online, this method returns when it is online

class dopyapi.databases.DatabaseConnection(connection)¶

This class holds connection information for the database cluster.

These information can be accessed as attributes.

uri¶

A connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.

Type:	str

database¶

The name of the default database.

Type:	str

host¶

The FQDN pointing to the database cluster’s current primary node.

Type:	str

port¶

The port on which the database cluster is listening.

Type:	int

user¶

The default user for the database.

Type:	str

password¶

The randomly generated password for the default user.

Type:	str

ssl¶

A boolean value indicating if the connection should be made over SSL.

Type:	bool

class dopyapi.databases.DatabaseConnectionPool(name, mode, size, db, user, connection=None, private_connection=None)¶

This class represents connection pool for a PostgreSQL database cluster

Connection pools can be used to allow a database to share its idle connections.

name¶

A unique name for the connection pool. Must be between 3 and 60 characters.

Type:	str

mode¶

The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement.

Type:	str

size¶

The desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster’s primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster.

Type:	int

db¶

The database for use with the connection pool.

Type:	str

user¶

The name of the user for use with the connection pool.

Type:	str

connection¶

An object containing the information required to access the database using the connection pool.

Type:	`DatabaseConnection`

private_connection¶

An object containing the information required to connect to the database using the connection pool via the private network.

Type:	`DatabaseConnection`

class dopyapi.databases.DatabaseFirewall(type, value)¶

This class represents a database firewall or inbound source.

It is used to allow access to the firewall from specific sources such as IP addresses, droplets, kubernetes clusters or resources tagged with some tag.

type¶

The type of resource that the firewall rule allows to access the database cluster. The possible values are: ‘droplet’, ‘k8s’, ‘ip_addr’, or ‘tag’

Type:	str

value¶

The ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster.

Type:	str

class dopyapi.databases.DatabaseUser(data)¶

A class that represents a user in the database cluster.

user¶

The user object as returned from the API.

Type:	dict

name¶

The name of database user.

Type:	str

password¶

The password of the database user.

Type:	str

role¶

A string representing the database user’s role. The value will be either “primary” or “normal”.

Type:	str

mysql_settings¶

An object containing addition configuration details for MySQL clusters

Type:	dict

mysql_settings dictionary has this key

auth_plugin (str): A string specifying the authentication method in use for connections to the MySQL user account. The valid values are “mysql_native_password” or “caching_sha2_password”.

Domains and Domain Records¶

class dopyapi.domains.Domain(data=None)¶

This class represents a single domain in Digital Ocean.

Domain records are only managed by Digital Ocean, the domain still needs to be bought using a domain registrar, and its NS records updated to the ones provided by Digital Ocean.

name¶

The name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name.

Type:	str

ttl¶

This value is the time to live for the records on this domain, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

Type:	int

zone_file¶

This attribute contains the complete contents of the zone file for the selected domain. Individual domain record resources should be used to get more granular control over records. However, this attribute can also be used to get information about the SOA record, which is created automatically and is not accessible as an individual record resource.

Type:	str

create(name, ip_address=None)¶

Create a new domain

We only need to provide the domain’s name and optionally and IP address to be assigned to the apex record.

Parameters:	name (str) – The domain name to add to the DigitalOcean DNS management interface. The name must be unique in DigitalOcean’s DNS system. The request will fail if the name has already been taken.. ip_address (str) – This optional attribute may contain an IP address. When provided, an A record will be automatically created pointing to the apex domain. default is None
Returns:	JSON object from the API
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod list(**kwargs)¶

This method returns a list of domains as defined by its arguments

Parameters:	page (int) – The page to fetch from all domains (defaults 1) per_page (int) – The number of domains per a single page (defaults 20)
Returns:	A list of domains
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

records(page=1, per_page=20)¶

Return a list of DomainRecord for this domain.

Parameters:	page (int) – The page to fetch from all domain records (defaults 1) per_page (int) – The number of domain records per a single page (defaults 20)
Returns:	A list of domain records
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

class dopyapi.domains.DomainRecord(domain, data=None)¶

This class represents a single domain record in Digital Ocean.

Each domain record belongs to a single domain.

id¶

A unique identifier for each domain record.

Type:	int

type¶

The type of the DNS record. For example: A, CNAME, TXT, … You can find a full list bellow.

Type:	str

name¶

The host name, alias, or service being defined by the record.

Type:	str

data¶

Variable data depending on record type. For example, the “data” value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.

Type:	str

priority¶

The priority for SRV and MX records.

Type:	int

port¶

The port for SRV records.

Type:	int

ttl¶

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

Type:	int

weight¶

The weight for SRV records.

Type:	int

flags¶

An unsigned integer between 0-255 used for CAA records.

Type:	int

tag¶

The parameter tag for CAA records. Valid values are “issue”, “issuewild”, or “iodef”

Type:	str

Record Types:

A: This record type is used to map an IPv4 address to a hostname.

AAAA: This record type is used to map an IPv6 address to a hostname.

CAA: As specified in RFC-6844, this record type can be used to restrict which certificate authorities are permitted to issue certificates for a domain.

CNAME: This record type defines an alias for your canonical hostname (the one defined by an A or AAAA record).

MX: This record type is used to define the mail exchanges used for the domain.

NS: This record type defines the name servers that are used for this zone.

TXT: This record type is used to associate a string of text with a hostname, primarily used for verification.

SRV: This record type specifies the location (hostname and port number) of servers for specific services.

SOA: This record type defines administrative information about the zone. Can only have ttl changed, cannot be deleted

create(type, **kwargs)¶

Create a new domain record

Here we pass the record’s type first, then we pass a number of arguments according to the records type.

Parameters:	type (str) – The type of the record A, AAAA, MX, etc…. name (str) – The host name, alias, or service being defined by the record. required for A, AAAA, CAA, CNAME, TXT and SRV types. data (str) – Variable data depending on record type. For example, the “data” value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates. required for A, AAAA, CAA, CNAME, MX, TXT, SRV, NS priority (int) – The priority of the host (for SRV and MX records. null otherwise). required for MX and SRV records. port (int) – The port that the service is accessible on (for SRV records only. null otherwise). reqired for SRV records. ttl (int) – This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested. There is a minimum ttl value of 30, unless it is not set. If not set, the default value is the value of the SOA record. For SOA records, defines the time to live for purposes of negative caching. required for SOA records weight (int) – The weight of records with the same priority (for SRV records only. null otherwise). required for SRV records. flags (int) – An unsigned integer between 0-255 used for CAA records. required for CAA records. tag (str) – The parameter tag for CAA records. Valid values are “issue”, “issuewild”, or “iodef” required for CAA records.
Returns:	JSON object from the API
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – When type is not supported or no enough data to create the record. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod list(domain_name, **kwargs)¶

This method returns a list of domain records as defined by its arguments

Parameters:	domain_name – The name of the domain to fetch records for it page (int) – The page to fetch from all domain records (defaults 1) per_page (int) – The number of domain records per a single page (defaults 20)
Returns:	A list of domain records
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

common¶

class dopyapi.common.DOJSONEncoder(*args, **kwargs)¶

This class is used to encode Digital Ocean resources as JSON objects

It can be used with json module to encode resources.

It is used as follows:

with open("droplets.json", "w") as outfile:
    json.dump(data, outfile, cls=do.DOJSONEncoder, sort_keys=True, indent=4)

Here data is a list that contains objects of Digital Ocean resources.

default(o)¶

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

droplets¶

class dopyapi.droplets.Droplet(data=None)¶

This class represents a single Droplet in Digital Ocean

You can use this class to create, update, delete and manage droplets on your Digital Ocean account, all droplet actions are available as instance methods and droplet attributes are available too.

id¶

A unique identifier for the droplet, it is generated when the droplet is created.

Type:	int

name¶

A human readable name for the droplet

Type:	str

memory¶

memory of the droplet in megabytes

Type:	int

vcpus¶

The number of virtual CPUs.

Type:	int

disk¶

The size of droplet disk in megabytes.

Type:	int

locked¶

A boolean value that tells if the droplet is locked preventing actions by users.

Type:	bool

created_at¶

A time object that tells when the droplet was created.

Type:	datetime.datetime

status¶: (str): A status string indicating the state of the droplet, it could be (“new”, “active”, “off”, “archive”).

backup_ids¶

An array of backup IDs that have been created for the droplet.

Type:	list

snapshot_ids¶

An array of snapshot IDs that have been created for the droplet.

Type:	list

features¶

An array of features enabled for the droplet.

Type:	list

region¶

A value for the region where the droplet was created.

Type:	Region

image¶

A value for the base image used to create the droplet

Type:	Image

size¶

A value for the size object used to create the droplet, this defines the amount of RAM, VCPUS and disk available for the droplet.

Type:	Size

size_slug¶

A unique slug identifier for the size of this droplet.

Type:	str

networks¶

An object that defines all networks connected to the droplet it includes a key of “IPv4” and “IPv6” if enabled, each key has an array of objects that contain network related information such as IP address, netmask and gateway plus more information specific for the network type.

Type:	dict

kernel¶

The current kernel for the droplet.

Type:	dict

next_backup_window¶

If backups are enabled for the droplet here we will find an object with keys to the start and end times for the backups.

Type:	dict

tags¶

An array of tags used when the droplet was created.

Type:	list

volume_ids¶

An array of block storage volumes attached to the droplet.

Type:	list

vpc_uuid¶

A string specifying the UUID of the VPC to which the Droplet is assigned.

Type:	str

Supported actions:

You can call these actions as methods on Droplet objects and return Action objects

enable_backups: Used to enable backups for the droplet

disable_backups: Used to disable backups for the droplet

reboot: used to reboot the droplet

power_cycle: Power cycle the droplet

shutdown: Attempt a gracefull shutdown of the droplet

power_off: hard shutdown of the droplet

power_on: power the droplet back on

restore: Restore this droplet to a previous backup, this takes an image arg and it should be the ID of a backup for current droplet.

password_reset: Request a password reset for the droplet.

resize: Resize the droplet for a new size, this takes size arg it should be the slug identifier for a size, and also a disk arg that can be True or False based on whether you want to resize disk as well or not.

rebuild: Rebuild this droplet with a new image, it takes image arg for the image that the droplet will use as new base image.

rename: Chnage the name of the droplet, it takes name arg.

change_kernel: Change the kernel of this droplet, it takes kernel arg which is the unique number of the new kernel to use.

enable_ipv6: Enable IPv6 for the droplet.

enable_private_networking: Enable private networking for the droplet.

snapshot: Take a snapshot for the droplet, it takes name arg.

classmethod actionByTagName(tag_name, action, **kwargs)¶

Execute the action on all droplets with a specific tag.

Parameters:	tag_name (str) – The name of tag to use. action (str) – The name of the action.
Returns:	This object represents the action used.
Return type:	Action
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod deleteByTagName(tag_name)¶

Delete all droplets whose tag_name equals tag_name

Parameters:	tag_name (str) – The name of the tag to delete droplets that match it
Returns:	A dictionary with one key “status” and value “deleted”.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

getPrivateIP()¶

Retrieve the private IP address of the droplet if available

This method makes sure that the droplet is active and returns its IP address as a string, if not available return None

Returns:	The private IP address or None if not available
Return type:	str

getPublicIP()¶

Retrieve the public IP address of the droplet

This method makes sure that the droplet is active and returns its IP address as a string

Returns:	The public IP address
Return type:	str

getPublicIPv6()¶

Retrieve the public v6 IP address of the droplet if available

This method makes sure that the droplet is active and returns its IP address as a string, if not available return None

Returns:	The public IP v6 address or None if not available
Return type:	str

classmethod list(**kwargs)¶

This method returns a list of droplets as defined by its arguments

Parameters:	page (int) – The page to fetch from all droplets (defaults 1) per_page (int) – The number of droplets per a single page (defaults 20)
Returns:	A list of droplets
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listBackups(**kwargs)¶

Return a list of backups for this droplet

Parameters:	page (int) – The page of backups to return per_page (int) – The number of backups per a single page (defaults 20)
Returns:	A list of backups, where each one is a dict
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listByTagName(tag_name, **kwargs)¶

This method returns a list of droplets that match the tag name

Parameters:	tag_name (str) – The tag used when fetching droplets page (int) – The page to fetch from all droplets (defaults 1) per_page (int) – The number of droplets per a single page (defaults 20)
Returns:	A list of droplets
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listDropletNeighbors()¶

This method returns a list of droplets that are on the same physical server.

The return value will be a list of lists.

Returns:	A list of droplets IDs
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listKernels(**kwargs)¶

Return a list of kernels that can be used with this droplet

Parameters:	page (int) – The page of kernels to return per_page (int) – The number of kernels per a single page (defaults 20)
Returns:	A list of kernels, where each kernel is a dict
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listNeighbors(**kwargs)¶

This method returns a list of droplets that are on the same physical server as this one

Parameters:	page (int) – The page to fetch from all droplets (defaults 1) per_page (int) – The number of droplets per a single page (defaults 20)
Returns:	A list of droplets
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listSnapshots(**kwargs)¶

Return a list of snapshots for this droplet

Parameters:	page (int) – The page of snapshots to return per_page (int) – The number of snapshots per a single page (defaults 20)
Returns:	A list of snapshots
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

waitReady()¶: Wait until a droplet is ready and running

firewalls¶

class dopyapi.firewalls.Firewall(data=None)¶

This class represents firewalls in DigitalOcean

You can use this class to create, update, delete and manage firewalls on your Digital Ocean account, all firewall attributes are available too.

id¶

A unique identifier for the firewall, it is generated when the firewall is created.

Type:	str

name¶

A human readable name for the firewall

Type:	str

pending_changes¶

A list of dictionaries each containing the fields “droplet_id”, “removing”, and “status”. It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied.

Type:	list

created_at¶

A time object that tells when the firewall was created.

Type:	datetime.datetime

status¶

A status string indicating the state of the firewall, it could be (“waiting”, “succeeded”, “failed”).

Type:	str

inbound_rules¶

A list of InboundRule objects which specify inbound rules applied in the firewall.

Type:	list

outbound_rules¶

A list of OutboundRule which specify outbound rules applied in the firewall.

Type:	list

droplet_ids¶

A list containing the IDs of the Droplets assigned to the firewall.

Type:	list

tags¶

A list containing the names of the Tags assigned to the firewall.

Type:	list

addDroplets(ids)¶

Add droplets to this Firewall

When adding droplets to a firewall, its rules are applied to traffic that tries to enter the droplet.

Parameters:	ids (list) – A list of droplets to be added, if you use a single value it will be converted to a list for you.
Returns:	JSON object from the API
Return type:	dictionary
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

addRules(rules)¶

Add rules to the firewall

Parameters:	tags (list, InboundRule, OutboundRule) – A list of rules to add, if you use a single object it is converted to a list for you.
Returns:	The JSON response from the API
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

addTags(tags)¶

Add tags to the firewall

Parameters:	tags (list, Tag) – A list of tags to add, it could be tag names or tag objects, if you use a single name or object it is converted to a list for you.
Returns:	The JSON response from the API
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

create(name, inbound_rules=[], outbound_rules=[])¶

Create a new Firewall

This method is used to create a new Firewall, if no rules are specified then these defaults are used: * An outbound rule that allows ICMP to all destinations. * An outbound rule that allows TCP to all ports and destinations. * An outbound rule that allows UDP to all ports and destinations.

Parameters:	name (str) – The name of the firewall inbound_rules (list) – A list of InboundRule objects. default [] outbound_rules (list) – A list of OutboundRule objects. default []
Returns:	JSON object from the API
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

droplets¶

Return droplet objects which are added to this firewall

Returns:	A list of droplet objects
Return type:	list

classmethod list(**kwargs)¶

This method returns a list of firewalls as defined by its arguments

Parameters:	page (int) – The page to fetch from all firewalls (defaults 1) per_page (int) – The number of firewalls per a single page (defaults 20)
Returns:	A list of firewalls
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

removeDroplets(ids)¶

Remove droplets from the Firewall

Parameters:	ids (list, Droplet) – A list of IDs or droplet objects to remove, you can pass a single ID or droplet here.
Returns:	JSON object from the API
Return type:	dictionary
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

removeRules(tags)¶

Remove rules from the Firewall

Parameters:	ids (list, InboundRule, OutboundRule) – A list of IDs or rule objects to remove, you can pass a single ID or rule object here.
Returns:	JSON object from the API
Return type:	dictionary
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

removeTags(tags)¶

Remove tags from the Firewall

Parameters:	ids (list, Tag) – A list of IDs or tag objects to remove, you can pass a single ID or tag here.
Returns:	JSON object from the API
Return type:	dictionary
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

class dopyapi.firewalls.InboundRule(protocol='tcp', ports='all', sources=None)¶

This class is used to represent an inbound rule in Digital Ocean Firewall

An inbound rule is applied when packets enter the firewall, it specifies what data is allowed in and any other data that does not match any inbound rule for a firewall is discarded and not allowed to reach the resources associated with the firewall.

sources¶

An object specifying locations from which inbound traffic will be accepted.

Type:	Location

getJSON()¶

Return a JSON representation of an inbound rule

This representation is used when making API calls.

Returns:	A dictionary for the inbound rule
Return type:	dict

class dopyapi.firewalls.Location(addresses=[], droplet_ids=[], load_balancer_uids=[], tags=[])¶

This class represents sources or destinations for firewall inbound and outbound rules.

A location could be a droplet, load balancer, Individual IP address or ranges: of them and droplets by tag.

addresses¶

A list of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the firewall will allow traffic.

Type:	list

droplet_ids¶

A list containing the IDs of the Droplets to which the firewall will allow traffic.

Type:	list

load_balancer_uids¶

A list containing the IDs of the load balancers to which the firewall will allow traffic.

Type:	list

tags¶

A list containing the names of Tags corresponding to groups of Droplets to which the firewall will allow traffic.

Type:	list

getJSON()¶

Return a JSON representation of a location object

This representation is used when making API calls.

Returns:	A dictionary for the location object
Return type:	dict

class dopyapi.firewalls.OutboundRule(protocol='tcp', ports='all', destinations=None)¶

This class is used to represent an outbound rule in Digital Ocean Firewall

An outbound rule is applied when packets leave the firewall, it specifies what data is allowed out and any other data that does not match any outbound rule for a firewall is discarded and not allowed.

destinations¶

An object specifying locations to which outbound traffic will be accepted.

Type:	Location

getJSON()¶

Return a JSON representation of an outbound rule

This representation is used when making API calls.

Returns:	A dictionary for the outbound rule
Return type:	dict

class dopyapi.firewalls.Rule(protocol='tcp', ports='all')¶

This class is the base class for inbound and outbound rules in Digital Ocean firewalls.

Here we find the protocol and ports attributes for a rule, the rest of attributes: can be found in InboundRule and OutboundRule classes.

protocol¶

The type of traffic to be allowed. This may be one of “tcp”, “udp”, or “icmp”.

Type:	str

ports¶

The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. “8000-9000”), or “0” when all ports are open for a protocol. For ICMP rules this parameter will always return “0”.

Type:	str

exception dopyapi.firewalls.RuleError(*args, **kwargs)¶

floating_ips¶

class dopyapi.floating_ips.FloatingIP(data=None)¶

This class represents a single Floating IP in Digital Ocean

You can use this class to create, update, delete and manage floating IPs on your Digital Ocean account, all floating IP actions are available as instance methods and floating IP attributes are available too.

ip¶

The public IP address of the floating IP. It also serves as its identifier.

Type:	str

region¶

The region that the floating IP is reserved to.

Type:	Region

droplet¶

The Droplet that the floating IP has been assigned to.

Type:	Droplet

Supported actions:

You call these actions as methods on FloatingIP and return Action objects

assign: Used to assign the floating IP to a droplet, it takes a single argument droplet_id which is the ID of droplet or a Droplet object.

unassign: Used to remove a floating IP from a droplet.

classmethod list(**kwargs)¶

This method returns a list of Floating IPs as defined by its arguments

Parameters:	page (int) – The page to fetch from all Floating IPs (defaults 1) per_page (int) – The number of Floating IPs per a single page (defaults 20)
Returns:	A list of Floating IPs
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

images¶

This module is contains the Image class to manage images in Digital Ocean, it also has some constants that contain the slug values for the most popular images in Digital Ocean, so you do not have to memorize all the image slugs.

class dopyapi.images.Distribution¶

This class could be used when creating a new private image to specify the distribution for the image.

arch_linux = 'Arch Linux'¶: Arch Linux

centos = 'CentOS'¶: CentOS

coreos = 'CoreOS'¶: CoreOS

debian = 'Debian'¶: Debian

fedora = 'Fedora'¶: Fedora

fedora_atomic = 'Fedora Atomic'¶: Fedora atomic

freebsd = 'FreeBSD'¶: FreeBSD

gentoo = 'Gentoo'¶: Gentoo

opensuse = 'openSUSE'¶: OpenSUSE

rancheros = 'RancherOS'¶: RancherOS

ubuntu = 'Ubuntu'¶: Ubuntu

class dopyapi.images.Image(data=None)¶

This class represents a single Image in Digital Ocean

This class is used to manage Images in Digital Ocean, it has methods to list all available images, create and delete images too.

id¶

A numberic ID for the image used in Digital Ocean to identify the image defaults (None)

Type:	int

name¶

A human readable name for the image used in User Interfaces. defaults (None)

Type:	str

type¶

The type of the image it could be one of the following (“snapshot”, “backup”, “custom”) defaults (None)

Type:	str

distribution¶

Here we store the base distribution used in the image. defaults (None)

Type:	str

slug¶

A unique string that identifies the image. defaults (None)

Type:	str

public¶

This checks if the image is public or not. defaults (None)

Type:	bool

regions¶

An array of regions where this image is available. defaults (None)

Type:	list

min_disk_size¶

The minimum size in gigabytes needed to create a droplet of this image. defaults (None)

Type:	int

size_gigabytes¶

The size of the image in gigabytes. defaults (None)

Type:	float

description¶

A description of the image. defaults (None)

Type:	str

tags¶

A list of tags for the image. defaults (None)

Type:	[]

status¶

This string indicates the status of a custom image, it could have one of these values (“NEW”, “available”, “pending”, “deleted”). defaults (None)

Type:	str

error_message¶

An error image for the custom image. defaults (None)

Type:	str

Supported actions:

You call these actions as methods on Image and return Action objects

transfer: This is used to transfer an image to another region, it takes one argument called region, it could be the regionss slug or a Region object.

convert: This is used to convert an image to a snapshot.

classmethod list(**kwargs)¶

Return a list of images based on arguments

Parameters:	page (int) – The page to fetch (defaults 1) per_page (int) – The number of images in the page (defaults 20)
Returns:	A list of image objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listApplication(**kwargs)¶

Return a list of application images

Parameters:	page (int) – The page to fetch (defaults 1) per_page (int) – The number of images in the page (defaults 20)
Returns:	A list of image objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listByTag(tag_name, **kwargs)¶

Return a list of images that match the tag

Parameters:	tag_name (str) – The name of the tag for the images page (int) – The page to fetch (defaults 1) per_page (int) – The number of images in the page (defaults 20)
Returns:	A list of image objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listDistribution(**kwargs)¶

Return a list of distribution images

Parameters:	page (int) – The page to fetch (defaults 1) per_page (int) – The number of images in the page (defaults 20)
Returns:	A list of image objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listUser(**kwargs)¶

Return a list of user private images

Parameters:	page (int) – The page to fetch (defaults 1) per_page (int) – The number of images in the page (defaults 20)
Returns:	A list of image objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

dopyapi.images.caprover_18_04 = 'caprover-18-04'¶: CapRover with Ubuntu 18.04

dopyapi.images.cassandra = 'cassandra'¶: Cassandra

dopyapi.images.centos = 'centos-8-x64'¶: Default centos, 8 with 64 bit

dopyapi.images.centos_6_32 = 'centos-6-x32'¶: CentOS 6, 32 bit

dopyapi.images.centos_6_64 = 'centos-6-x64'¶: CentOS 6, 64 bit

dopyapi.images.centos_7_64 = 'centos-7-x64'¶: CentOS 7, 64 bit

dopyapi.images.centos_8_32 = 'centos-8-x32'¶: CentOS 8, 32 bit

dopyapi.images.centos_8_64 = 'centos-8-x64'¶: CentOS 8, 64 bit

dopyapi.images.coreos_alpha = 'coreos-alpha'¶: CoreOS alpha

dopyapi.images.coreos_beta = 'coreos-beta'¶: CoreOS beta

dopyapi.images.coreos_stable = 'coreos-stable'¶: CoreOS stable

dopyapi.images.debian = 'debian-10-x64'¶: Default debian image, 10 64 bit.

dopyapi.images.debian_10_64 = 'debian-10-x64'¶: Debian 10 64 bit

dopyapi.images.debian_9_64 = 'debian-9-x64'¶: Debian 9 64 bit

dopyapi.images.docker = 'docker-18-04'¶: Docker on Ubuntu 18.04

dopyapi.images.fedora = 'fedora-30-x64'¶: Default fedora 30 with 64 bit

dopyapi.images.fedora_27_64 = 'fedora-27-x64'¶: Fedora 27 64 bit

dopyapi.images.fedora_28_64 = 'fedora-28-x64'¶: Fedora 28 64 bit

dopyapi.images.fedora_28_64_atomic = 'fedora-28-x64-atomic'¶: Fedora 28 64 bit, atomic

dopyapi.images.fedora_30_64 = 'fedora-30-x64'¶: Fedora 30 64 bit

dopyapi.images.freebsd = 'freebsd-12-x64'¶: Default FreeBSD image, 12 with 64 bit

dopyapi.images.freebsd_10_4_64 = 'freebsd-10-4-x64'¶: FreeBSD 10.4 64 bit

dopyapi.images.freebsd_10_4_64_zfs = 'freebsd-10-4-x64-zfs'¶: FreeBSD 10.4 64 bit with ZFS

dopyapi.images.freebsd_11_64_ufs = 'freebsd-11-x64-ufs'¶: FreeBSF 11 64 bit with UFS

dopyapi.images.freebsd_11_64_zfs = 'freebsd-11-x64-zfs'¶: FreeBSF 11 64 bit with ZFS

dopyapi.images.freebsd_12_64 = 'freebsd-12-x64'¶: FreeBSF 12 64 bit

dopyapi.images.freebsd_12_64_zfs = 'freebsd-12-x64-zfs'¶: FreeBSF 12 64 bit with ZFS

dopyapi.images.gitea_18_04 = 'gitea-18-04'¶: GitEA with Ubuntu 18.04

dopyapi.images.rancheros = 'rancheros'¶: RancherOS

dopyapi.images.skaffolder_18_04 = 'skaffolder-18-04'¶: Skaffolder with Ubuntu 18.04

dopyapi.images.ubuntu = 'ubuntu-18-04-x64'¶: This creates an Ubuntu 18.04 image by default.

dopyapi.images.ubuntu_14_04_32 = 'ubuntu-14-04-x32'¶: Ubuntu 14.04 32 bit image

dopyapi.images.ubuntu_14_04_64 = 'ubuntu-14-04-x64'¶: Ubuntu 14.04 64 bit image

dopyapi.images.ubuntu_16_04_32 = 'ubuntu-16-04-x32'¶: Ubuntu 16.04 32 bit image

dopyapi.images.ubuntu_16_04_64 = 'ubuntu-16-04-x64'¶: Ubuntu 16.04 64 bit image

dopyapi.images.ubuntu_18_04_64 = 'ubuntu-18-04-x64'¶: Ubuntu 18.04 64 bit image

dopyapi.images.ubuntu_19_10_64 = 'ubuntu-19-10-x64'¶: Ubuntu 19.10 64 bit image

invoices¶

class dopyapi.invoices.Invoice(data=None)¶

This class represents a single Invoice in Digital Ocean.

An invoice is generated on the first day of each month. An invoice preview is generated daily.

invoice_uuid¶

The UUID of the invoice. The canonical reference for the invoice.

Type:	str

amount¶

Total amount of the invoice, in USD. This will reflect month-to-date usage in the invoice preview.

Type:	str

invoice_period¶

Billing period of usage for which the invoice is issued, in YYYY-MM format.

Type:	str

updated_at¶

Time the invoice was last updated. This is only included with the invoice preview.

Type:	datetime

getCSV()¶

Get a CSV summary of the invoice

Returns:	CSV data as a string
Return type:	str

getPDF()¶

Get a PDF summary of the invoice

Returns:	A bytes object for the PDF data.
Return type:	bytes

classmethod list(**kwargs)¶

This method returns a list of invoices as defined by its arguments

Parameters:	page (int) – The page to fetch from all invoices (defaults 1) per_page (int) – The number of invoices per a single page (defaults 20)
Returns:	A list of invoices
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

saveCSV(file=None)¶

Save a CSV summary to a file.

Parameters:	file – The name of the file to save CSV data to it, default is {invoice_period}.csv

savePDF(file=None)¶

Save a PDF summary to a file.

Parameters:	file – The name of the file to save CSV data to it, default is {invoice_period}.pdf

class dopyapi.invoices.InvoiceItem(invoice_uuid, data=None)¶

This class represents a single Invoice item in Digital Ocean.

Invoice Items show details for each invoice, such as product names, their usage time and their price.

product¶

Name of the product being billed in the invoice item.

Type:	str

resource_uuid¶

UUID of the resource billing in the invoice item if available.

Type:	str

resource_id¶

ID of the resource billing in the invoice item if available.

Type:	str

group_description¶

Description of the invoice item when it is a grouped set of usage, such as DOKS or databases.

Type:	str

description¶

Description of the invoice item.

Type:	str

amount¶

Billed amount of this invoice item. Billed in USD.

Type:	str

duration¶

Duration of time this invoice item was used and subsequently billed.

Type:	str

duration_unit¶

Unit of time for duration.

Type:	str

start_time¶

Time the invoice item began to be billed for usage.

Type:	datetime

end_time¶

Time the invoice item stoped being billed for usage.

Type:	datetime

project_name¶

Name of the DigitalOcean Project this resource belongs to.

Type:	str

classmethod list(invoice_uuid, **kwargs)¶

This method returns a list of invoice items as defined by its arguments

Parameters:	page (int) – The page to fetch from all invoice items (defaults 1) per_page (int) – The number of invoice items per a single page (defaults 20)
Returns:	A list of invoice items
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listPreview(**kwargs)¶

This method returns a list of invoice items for the preview invoice generated daily as defined by its arguments

Parameters:	page (int) – The page to fetch from all invoice items (defaults 1) per_page (int) – The number of invoice items per a single page (defaults 20)
Returns:	A list of invoice items
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

class dopyapi.invoices.InvoiceSummary(invoice_uuid, data=None)¶

This class represents a single Invoice summary in Digital Ocean.

invoice_uuid¶

UUID of invoice.

Type:	str

billing_period¶

Billing period of usage for which the invoice is issued, in YYYY-MM format.

Type:	str

amount¶

Total amount of the invoice, in USD. This will reflect month-to-date usage in the invoice preview.

Type:	str

user_name¶

Name of the DigitalOcean customer being invoiced.

Type:	str

user_billing_address¶

The billing address of the customer being invoiced.

Type:	dict

user_company¶

Company of the DigitalOcean customer being invoiced, if set.

Type:	str

user_email¶

Email of the DigitalOcean customer being invoiced.

Type:	str

product_charges¶

A summary of the product usage charges contributing to the invoice. This will include an amount, and grouped aggregates by resource type under the items key.

Type:	dict

overages¶

A summary of the overages contributing to the invoice.

Type:	dict

taxes¶

A summary of the taxes contributing to the invoice.

Type:	dict

credits_and_adjustments¶

A summary of the credits and adjustments contributing to the invoice.

Type:	dict

Kuberenetes Cluster¶

A module used to interact with Digital Ocean Kuberenetes Cluster API.

class dopyapi.doks.DOKS(data=None)¶

This class represents a single kuberenetes cluster in Digital Ocean.

The kuberenetes cluster simplifies kuberenetes management, it supports these versions of kuberenetes (1.16.14-do.0, 1.17.11-do.0, 1.18.9-do.0).

id¶

A unique ID that can be used to identify and reference a Kubernetes cluster.

Type:	str

name¶

A human-readable name for a Kubernetes cluster.

Type:	str

endpoint¶

The base URL of the API server on the Kubernetes master node.

Type:	str

region¶

The slug identifier for the region where the Kubernetes cluster is located.

Type:	str

version¶

The slug identifier for the version of Kubernetes used for the cluster. If set to a minor version (e.g. “1.14”), the latest version within it will be used (e.g. “1.14.6-do.1”); if set to “latest”, the latest published version will be used.

Type:	str

auto_upgrade¶

A boolean value indicating whether the cluster will be automatically upgraded to new patch releases during its maintenance window.

Type:	bool

surge_upgrade¶

A boolean value indicating whether surge upgrade is enabled/disabled for the cluster. Surge upgrade makes cluster upgrades fast and reliable by bringing up new nodes before destroying the outdated nodes.

Type:	bool

ipv4¶

The public IPv4 address of the Kubernetes master node.

Type:	str

cluster_subnet¶

The range of IP addresses in the overlay network of the Kubernetes cluster in CIDR notation.

Type:	str

service_subnet¶

The range of assignable IP addresses for services running in the Kubernetes cluster in CIDR notation.

Type:	str

vpc_uuid¶

A string specifying the UUID of the VPC to which the Kubernetes cluster is assigned.

Type:	str

tags¶

An array of tags applied to the Kubernetes cluster. All clusters are automatically tagged “k8s” and “k8s:$K8S_CLUSTER_ID.”

Type:	list

maintenance_policy¶

An object specifying the maintenance window policy for the Kubernetes cluster (see table below).

Type:	str

node_pools¶

An object specifying the details of the worker nodes available to the Kubernetes cluster (see table below).

Type:	list

created_at¶

A time value given in ISO8601 combined date and time format that represents when the Kubernetes cluster was created.

Type:	datetime

updated_at¶

A time value given in ISO8601 combined date and time format that represents when the Kubernetes cluster was last updated.

Type:	datetime

status¶

An object containing a “state” attribute whose value is set to a string indicating the current status of the node. Potential values include running, provisioning, and errored.

Type:	str

Maintenance Policy

This is a dictionary which defines when cluster maintenance will run, it has the following keys:

start_time (str): The start time in UTC of the maintenance window policy in 24-hour clock format / HH:MM notation (e.g., 15:00).

day (str): The day of the maintenance window policy. May be one of “monday” through “sunday”, or “any” to indicate an arbitrary week day.

Node Pools

This is a list of NodePool.

addNodePool(size, name, count, tags=[], labels={}, auto_scale=False, min_nodes=0, max_nodes=0, taints=[])¶

Create a new node pool.

Parameters:	size (str) – The size of Node Pool. name (str) – The name of the Node Pool. count (int) – The number of nodes in the Pool. tags (list) – An array of tags to be assigned to the pool. labels (dictionary) – A dictionary of user defined values assigned to the pool. auto_scale (bool) – A boolean value indicating whether auto-scaling is enabled for this node pool. This requires DOKS versions at least 1.13.10-do.3, 1.14.6-do.3, or 1.15.3-do.3. min_nodes (int) – The minimum number of nodes that this node pool can be auto-scaled to. This will fail validation if the additional nodes will exceed your account droplet limit. max_nodes (int) – The maximum number of nodes that this node pool can be auto-scaled to. This can be 0, but your cluster must contain at least 1 node across all node pools. taints (list) – An array of taints to apply to all nodes in a pool. Taints will automatically be applied to all existing nodes and any subsequent nodes added to the pool. When a taint is removed, it is removed from all nodes in the pool.
Returns:	A dictionary object for the newly created node pool.
Return type:	dict

clusterlint(run_id=None)¶

Retrieve clusterlint diagnostic.

If no run_id is provided then the last one is used.

Parameters:	run_id (str) – The clusterlint run id to fetch.

clusterlintCheck()¶: Run a clusterlint on the kuberenetes cluster.

credentials(expiry_seconds=0)¶

Return the credentials of the cluster.

Parameters:	expiry_seconds (int) – The expiry of the credentials in seconds, if not set or 0 is used then a default of 7 days is used.
Returns:	A dictionary object which holds keys and values used to connect to the cluster, it has these keys (server, certificate_authority_data, client_certificate_data , client_key_data, token, expires_at).
Return type:	dict

deleteNode(id, node_id, replace=0, skip_drain=0)¶

Delete an existing node in a node pool by its ID.

Parameters:	id (str) – The ID of node pool. node_id (str) – The ID of node to delete.
Returns:	A dictionary object with one key status.
Return type:	dict

deleteNodePool(id)¶

Delete an existing node pool by ID.

Parameters:	id (str) – The ID of node pool to delete.
Returns:	A dictionary object of one key status.
Return type:	dict

getNodePool(id)¶

Get a node pool by ID.

Parameters:	id (str) – The ID of node pool to get.
Returns:	A ndoe pool object.
Return type:	`NodePool`
Raises:	`ResourceNotFoundError` – When the id of node pool is not found.

kubeconfig(expiry_seconds=0)¶

Get the kubeconfig of the cluster.

Parameters:	expiry_seconds (int) – The expiry of the kubeconfig in seconds, if not set or 0 is used then a default of 7 days is used.
Returns:	A byte object which contains the kubeconfig used to connect to the cluster.
Return type:	bytes

classmethod list(**kwargs)¶

Return a list of kubernetes clusters as defined by its arguments.

Parameters:	page (int) – The page to fetch from all clusters (defaults 1) per_page (int) – The number of clusters per a single page (defaults 20)
Returns:	A list of kubernetes clusters
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listNodePools()¶

Return a list of node pools in the cluster.

Returns:	A list of `NodePool` objects.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or when the database cluster engine is redis `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listNodes(id)¶

Return a list of nodes in a pool by ID.

Args: id (str): The ID of node pool to get its nodes.

Returns:	A list of `Node` objects.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 or when the database cluster engine is redis `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

options()¶: Return an object of available versions and sizes.

updateNodePool(id, name, count, tags=[], labels={}, auto_scale=False, min_nodes=0, max_nodes=0, taints=[])¶

Update an existing node pool by ID.

Parameters:	id (str) – The ID of node pool to update. name (str) – The name of the Node Pool. count (int) – The number of nodes in the Pool. tags (list) – An array of tags to be assigned to the pool. labels (dictionary) – A dictionary of user defined values assigned to the pool. auto_scale (bool) – A boolean value indicating whether auto-scaling is enabled for this node pool. This requires DOKS versions at least 1.13.10-do.3, 1.14.6-do.3, or 1.15.3-do.3. min_nodes (int) – The minimum number of nodes that this node pool can be auto-scaled to. This will fail validation if the additional nodes will exceed your account droplet limit. max_nodes (int) – The maximum number of nodes that this node pool can be auto-scaled to. This can be 0, but your cluster must contain at least 1 node across all node pools. taints (list) – An array of taints to apply to all nodes in a pool. Taints will automatically be applied to all existing nodes and any subsequent nodes added to the pool. When a taint is removed, it is removed from all nodes in the pool.
Returns:	A dictionary object with one key status.
Return type:	dict
Raises:	`ResourceNotFoundError` – When the node pool is not found.

upgrade(version)¶

Upgrade current kuberenetes cluster to specific version.

verion¶

The slug identifier for the version of Kubernetes to upgrade to. Use upgrades() method for available versions.

Type:	str

Raises:	`ResourceNotFoundError` – When the version is not available for upgrade

upgrades()¶

Return an array of available version upgrades for current cluster.

Returns:

A list of dictionaries for available upgardes, each one has these keys:

slug (str): The verion slug used in Digital Ocean.

kubernetes_version (str): The corresponding Digital Ocean service.

Return type: list

waitReady()¶: Wait untill the cluster is online, this method returns when it is online.

dopyapi.doks.DOKS_V_17 = '1.17.13'¶: Kuberenetes Version 17 slug

dopyapi.doks.DOKS_V_18 = '1.18.10'¶: Kuberenetes Version 18 slug

dopyapi.doks.DOKS_V_19 = '1.19.3'¶: Kuberenetes Version 19 slug

class dopyapi.doks.Node(id=None, name=None, status=None, created_at=None, updated_at=None, droplet_id=None)¶

This class represents a single node in the Node Pool.

Each node has these attributes

id¶

A unique ID that can be used to identify and reference the node.

Type:	str

name¶

An automatically generated, human-readable name for the node.

Type:	str

status¶

An object containing a “state” attribute whose value is set to a string indicating the current status of the node. Potentialvalues include running, provisioning, and errored.

Type:	dict

created_at¶

A time value given in ISO8601 combined date and time format that represents when the node was created.

Type:	datetime

updated_at¶

A time value given in ISO8601 combined date and time format that represents when the node was created.

Type:	datetime

class dopyapi.doks.NodePool(name, size, count, labels={}, tags=[], auto_scale=False, min_nodes=0, max_nodes=0, nodes=[], id=None, taints=[])¶

This class represents a pool of ndoes for kubernetes clusters.

Each pool of nodes defines a number of nodes with a specific size: name, labels and auto_scale attribute.

size¶

The slug identifier for the type of Droplet to be used as workers in the node pool.

Type:	str

name¶

A human-readable name for the node pool.

Type:	str

count¶

The number of Droplet instances in the node pool.

Type:	int

labels¶

An object containing a set of Kubernetes labels. The keys are user-defined.

Type:	dict

auto_scale¶

A boolean value indicating whether auto-scaling is enabled for this node pool. This requires DOKS versions at least 1.13.10-do.3, 1.14.6-do.3, or 1.15.3-do.3.

Type:	bool

min_nodes¶

The minimum number of nodes that this node pool can be auto-scaled to. This will fail validation if the additional nodes will exceed your account droplet limit.

Type:	int

max_nodes¶

The maximum number of nodes that this node pool can be auto-scaled to. This can be 0, but your cluster must contain at least 1 node across all node pools.

Type:	int

getJSON()¶: Return JSON representation of NodePool.

load balancers¶

class dopyapi.loadbalancers.ForwardingRule(entry_protocol='http', entry_port=80, target_protocol='http', target_port=80, certificate_id='', tls_passthrough=False)¶

This class represents a single forwarding rule for Load Balancers

These rules specify how traffic is routed from load balancer to internal droplets assigned for the load balancer, it tells type of traffic it accepts, port and how to send traffic to the droplet, it also tells whether SSL traffic is terminated at the load balancer or the droplets assigned to it.

entry_protocol¶

The protocol used for traffic to the load balancer. The possible values are: “http”, “https”, “http2”, or “tcp”. (default http)

Type:	str

entry_port¶

An integer representing the port on which the load balancer instance will listen. (default 80)

Type:	int

target_protocol¶

The protocol used for traffic from the load balancer to the backend Droplets. The possible values are: “http”, “https”, “http2”, or “tcp”. (default http)

Type:	str

target_port¶

An integer representing the port on the backend Droplets to which the load balancer will send traffic. (default 80)

Type:	int

certificate_id¶

The ID of the TLS certificate used for SSL termination if enabled.

Type:	str

tls_passthrough¶

A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. (default true)

Type:	bool

getJSON()¶

Return the JSON representation of a forwarding rule.

This will be used when sending API requests to create a load balancer.

Returns:	A dictionary of key/value pairs for the rule’s attributes.
Return type:	dict

class dopyapi.loadbalancers.HealthCheck(protocol='http', port=80, path='/', check_interval_seconds=10, response_timeout_seconds=5, healthy_threshold=5, unhealthy_threshold=3)¶

This class represents health check objects for Digital Ocean Load Balancer

The health check is used to tell if a droplet is responding or not. The load balancer automatically stops sending traffic to unhealthy droplets.

protocol¶

The protocol used for health checks sent to the backend Droplets. The possible values are “http” or “tcp”.

Type:	str

port¶

An integer representing the port on the backend Droplets on which the health check will attempt a connection.

Type:	int

path¶

The path on the backend Droplets to which the load balancer instance will send a request.

Type:	str

check_interval_seconds¶

The number of seconds between between two consecutive health checks.

Type:	int

response_timeout_seconds¶

The number of seconds the load balancer instance will wait for a response until marking a health check as failed.

Type:	int

unhealthy_threshold¶

The number of times a health check must fail for a backend Droplet to be marked “unhealthy” and be removed from the pool.

Type:	int

healthy_threshold¶

The number of times a health check must pass for a backend Droplet to be marked “healthy” and be re-added to the pool.

Type:	int

class dopyapi.loadbalancers.LoadBalancer(data=None)¶

This class is used to manage Load Balancer in Digital Ocean.

You can use this class to create, update and delete load balancers and assign droplets to them, also specify their forwarding rules.

id¶

A unique ID that can be used to identify and reference a load balancer.

Type:	str

name¶

A human-readable name for a load balancer instance.

Type:	str

ip¶

An attribute containing the public-facing IP address of the load balancer.

Type:	str

alogrithm¶

The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either “round_robin” or “least_connections”.

Type:	str

status¶

A status string indicating the current state of the load balancer. This can be “new”, “active”, or “errored”.

Type:	str

created_at¶

A time value that represents when the load balancer was created.

Type:	datetime.datetime

forwarding_rules¶

A list of objects specifying the forwarding rules for a load balancer.

Type:	list

health_checks¶

An object specifying health check settings for the load balancer.

Type:	HealthCheck

sticky_sessions¶

An object specifying sticky sessions settings for the load balancer.

Type:	StickySession

region¶

The region where the load balancer instance is located.

Type:	Region

tag¶

The name of a Droplet tag corresponding to Droplets assigned to the load balancer.

Type:	str

droplet_ids¶

A list containing the IDs of the Droplets assigned to the load balancer.

Type:	list

redirect_http_to_https¶

A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.

Type:	bool

enable_proxy_protocol¶

A boolean value indicating whether PROXY Protocol is in use.

Type:	bool

addDroplets(droplets)¶

Add new droplets to the load balancer.

If the load balancer was created with a tag attribute, then this method will throw an error because you cannot add droplets to load balancers with a tag attribute, droplets in this case are added automatically when you tag a droplet with this tag, you can pass a single droplet object, or a list of droplet objects, you can also pass IDs instead of objects.

Parameters:	droplets (list) – A list of droplets to add, you can pass a single droplet and it will be converted to a list.
Returns:	JSON object from the API
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

addRules(rules)¶

Add new rules to the load balancer.

Use this method to update the forwarding rules of a load balancer.

Parameters:	rules (list) – A list of rules to add, you can pass a single `ForwardingRule` object and it will be converted to a list.
Returns:	JSON object from the API
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

create(**kwargs)¶

Create a new load balancer

If no forwarding rule is specified then a default one that forwards HTTP traffic on port 80 to port 80 without SSL is used.

Returns:	JSON object from the API
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

deleteDroplets(droplets)¶

Delete droplets from a load balancer.

Parameters:	droplets (list) – A list of droplets to delete, you can pass a single droplet and it will be converted to a list.
Returns:	A dictionary with one key “status” and value “deleted”.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

deleteRules(rules)¶

Delete rules from a load balancer.

Parameters:	rules (list) – A list of rules to delete, you can pass a single `ForwardingRule` object and it will be converted to a list.
Returns:	A dictionary with one key “status” and value “deleted”.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

classmethod list(**kwargs)¶

This method returns a list of load balancers as defined by its arguments

Parameters:	page (int) – The page to fetch from all load balancers (defaults 1) per_page (int) – The number of load balancers per a single page (defaults 20)
Returns:	A list of load balancers
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

class dopyapi.loadbalancers.StickySession(type='none', cookie_name='do-lb', cookie_ttl_seconds=60)¶

A class to represent sticky sessions used in Digital Ocean Load Balancer

type¶

An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are “cookies” or “none”. If not specified, the default value is “none”.

Type:	str

cookie_name¶

The name to be used for the cookie sent to the client. This attribute is required when using “cookies” for the sticky sessions type.

Type:	str

cookie_ttl_seconds¶

The number of seconds until the cookie set by the load balancer expires. This attribute is required when using “cookies” for the sticky sessions type.

Type:	int

projects¶

class dopyapi.projects.Project(data=None)¶

This class represents a project in Digital Ocean.

A project allows you to organize your resources in groups that fit the applications you run on Digital Ocean.

id¶

The unique universal identifier of this project.

Type:	str

owner_uuid¶

The unique universal identifier of the project owner.

Type:	str

owner_id¶

The integer id of the project owner.

Type:	int

name¶

The human-readable name for the project.

Type:	str

description¶

An optional description text for the project.

Type:	str

purpose¶

The purpose of the project, it can have one of these values (“Just trying out DigitalOcean”, “Class project / Educational purposes” , “Website or blog”, “Web Application”, “Service or API”, “Mobile Application” , “Machine learning / AI / Data processing”, “IoT”, “Operational / Developer tooling”) if you use a valume other than these it will be stored as “Other: your custom purpose”.

Type:	str

environment¶

The environment for project resources, it can have one of these values (“Development”, “Staging”, “Production”).

Type:	str

is_default¶

If true, all resources will be added to this project if no project is specified.

Type:	bool

created_at¶

The time when the project was created.

Type:	datetime

updated_at¶

The time when the project was updated.

Type:	datetime

classmethod getDefault()¶

Return the default project objects

Returns:	The Project for the default project
Return type:	Project
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod list(**kwargs)¶

Return a list of project instances.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20)
Returns:	A list of project instances.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

class dopyapi.projects.Purpose¶

A class that contains valid values for the project’s purpose attribute.

ai = 'Machine learning / AI / Data processing'¶: A project for Artificial Intelligence purposes.

api = 'Service or API'¶: A project to host an API.

blog = 'Website or blog'¶: A project for a blog or website.

education = 'Class project / Educational purposes'¶: A project for educational purposes.

iot = 'IoT'¶: A project for an IOT platform.

mobile = 'Mobile Application'¶: A project for a mobile application.

tools = 'Operational / Developer tooling'¶: A project for Developer and Operational tools

trying = 'Just trying out DigitalOcean'¶: A project to try Digital Ocean services.

web = 'Web Application'¶: A project to host a web application.

regions¶

class dopyapi.regions.Region(data=None)¶

This class represents a single region in Digital Ocean

A region represents a dataceneter where droplets can be created and images can be transferred.

slug¶

A human readable string that can be used as a unique identifier for each region.

Type:	str

name¶

The display name for the region

Type:	str

sizes¶

A list of size slugs that are available for this region

Type:	list

available¶

A boolean that checks if the region is available or not

Type:	bool

features¶

An array of features available for this region

Type:	list

classmethod list(**kwargs)¶

Return a list of regions based on arguments

Parameters:	page (int) – The page to return per_page (int) – The number of regions in a single page
Returns:	A list of region objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

sizes¶

This module contains the Size class to manage all available sizes in Digital Ocean used when creating droplets, it also has a set of constants which contain the values for size slugs, so you do not need to memorize all of these slugs when creating a new droplet.

class dopyapi.sizes.Size(data=None)¶

This class represents sizes in DO which are used when creating droplets.

A size includes the amount of RAM, Virtual CPUs, disk and transfer available for a droplet once created using it.

slug¶

A human-readable string that is used to uniquely identify each size.

Type:	str

available¶

Whether this size is available for droplet creation or not.

Type:	bool

transfer¶

The amount of bandwidth transfer available for droplets of this size.

Type:	float

price_monthly¶

The monthly cost for this size in US dollars.

Type:	float

price_hourly¶

The hourly cost for this size in US dollars.

Type:	float

memory¶

The RAM available for this size.

Type:	int

vcpus¶

The Virtual CPUs available for this size.

Type:	int

disk¶

The amount of disk space available for this size.

Type:	int

regions¶

A list containing the region slugs where this size is available for Droplet creates.

Type:	list

classmethod list(**kwargs)¶

Return a list of size instances.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of size instances in a single page. (default 20)
Returns:	A list of sizes instances.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

dopyapi.sizes.big = 's-4vcpu-8gb'¶: A big size, 4vCPU, 8 GB RAM

dopyapi.sizes.c_2_4 = 'c-2'¶: 2 vCPU, 4 GB RAM

dopyapi.sizes.c_4_8 = 'c-4'¶: 4 vCPU, 8 GB RAM

dopyapi.sizes.db_16_64 = 'db-s-16vcpu-64gb'¶

16 vCPU 64 GB RAM, 1.12 TB HD

Type:	Database size

dopyapi.sizes.db_1_1 = 'db-s-1vcpu-1gb'¶

1 vCPU 1 GB RAM, 10 GB HD

Type:	Database size

dopyapi.sizes.db_1_2 = 'db-s-1vcpu-2gb'¶

1 vCPU 2 GB RAM, 25 GB HD

Type:	Database size

dopyapi.sizes.db_2_4 = 'db-s-2vcpu-4gb'¶

2 vCPU 4 GB RAM, 38 GB HD

Type:	Database size

dopyapi.sizes.db_4_8 = 'db-s-4vcpu-8gb'¶

4 vCPU 8 GB RAM, 115 GB HD

Type:	Database size

dopyapi.sizes.db_6_16 = 'db-s-6vcpu-16gb'¶

6 vCPU 16 GB RAM, 270 GB HD

Type:	Database size

dopyapi.sizes.db_8_32 = 'db-s-8vcpu-32gb'¶

8 vCPU 32 GB RAM, 580 GB HD

Type:	Database size

dopyapi.sizes.db_large = 'db-s-4vcpu-8gb'¶

4 vCPU 8 GB RAM, 115 GB HD

Type:	Large database size

dopyapi.sizes.db_medium = 'db-s-2vcpu-4gb'¶

2 vCPU 4 GB RAM, 38 GB HD

Type:	Medium database size

dopyapi.sizes.db_small = 'db-s-1vcpu-2gb'¶

1 vCPU 2 GB RAM, 25 GB HD

Type:	Small database size

dopyapi.sizes.db_tiny = 'db-s-1vcpu-1gb'¶

1 vCPU 1 GB RAM, 10 GB HD

Type:	Tiny database size

dopyapi.sizes.db_xlarge = 'db-s-6vcpu-16gb'¶

6 vCPU 16 GB RAM, 270 GB HD

Type:	X large database size

dopyapi.sizes.db_xxlarge = 'db-s-8vcpu-32gb'¶

8 vCPU 32 GB RAM, 580 GB HD

Type:	XX large database size

dopyapi.sizes.db_xxxlarge = 'db-s-16vcpu-64gb'¶

16 vCPU 64 GB RAM, 1.12 TB HD

Type:	XXX large database size

dopyapi.sizes.g_2_8 = 'g-2vcpu-8gb'¶: 2 vCPU, 8 GB RAM

dopyapi.sizes.gd_2_8 = 'gd-2vcpu-8gb'¶: 2 vCPU, 8 GB RAM

dopyapi.sizes.large = 's-6vcpu-16gb'¶: A large size, 6vCPU, 16 GB RAM

dopyapi.sizes.m_1_8 = 'm-1vcpu-8gb'¶: 1 vCPU, 8 GB RAM

dopyapi.sizes.m_2_16 = 'm-16gb'¶: 2 vCPU, 16 GB RAM

dopyapi.sizes.medium = 's-2vcpu-4gb'¶: A medium size, 2vCPU, 4 GB RAM

dopyapi.sizes.s_1_1 = 's-1vcpu-1gb'¶: 1 vCPU, 1 GB RAM

dopyapi.sizes.s_1_2 = 's-1vcpu-2gb'¶: 1 vCPU, 2 GB RAM

dopyapi.sizes.s_1_3 = 's-1vcpu-3gb'¶: 1 vCPU, 3 GB RAM

dopyapi.sizes.s_2_2 = 's-2vcpu-2gb'¶: 2 vCPU, 2 GB RAM

dopyapi.sizes.s_2_4 = 's-2vcpu-4gb'¶: 2 vCPU, 4 GB RAM

dopyapi.sizes.s_3_1 = 's-3vcpu-1gb'¶: 3 vCPU, 1 GB RAM

dopyapi.sizes.s_4_8 = 's-4vcpu-8gb'¶: 4 vCPU, 8 GB RAM

dopyapi.sizes.s_6_16 = 's-6vcpu-16gb'¶: 6 vCPU, 16 GB RAM

dopyapi.sizes.small = 's-1vcpu-3gb'¶: A small size, 1vCPU, 3 GB RAM

dopyapi.sizes.t_0_1 = '512mb'¶: 1 vCPU, 512 MB RAM

dopyapi.sizes.t_1_1 = '1gb'¶: 1 vCPU, 1 GB RAM

dopyapi.sizes.t_2_2 = '2gb'¶: 2 vCPU, 2 GB RAM

dopyapi.sizes.t_2_4 = '4gb'¶: 2 vCPU, 4 GB RAM

dopyapi.sizes.t_4_8 = '8gb'¶: 4 vCPU, 8 GB RAM

dopyapi.sizes.tiny = 's-1vcpu-1gb'¶: A tiny size, 1vCPU, 1 GB RAM

snapshots¶

class dopyapi.snapshots.Snapshot(data=None)¶

This class represents snapshots in Digital Ocean.

Each snapshot is a saved image from a droplet or a block storage volume, the resource_type attribute defines if the snapshot is for a droplet or volume.

id¶

The unique identifier for the snapshot.

Type:	str

name¶

A human-readable name for the snapshot.

Type:	str

created_at¶

The date where the snapshot was created.

Type:	datetime

regions¶

A list of region slugs that the image is available in.

Type:	list

resource_id¶

A unique identifier for the resource that the snapshot is associated with.

Type:	str

resource_type¶

The type of resource for this snapshot.

Type:	str

min_disk_size¶

The minimum size in GB required for a volume or droplet to use this snapshot.

Type:	int

size_gigabytes¶

The size of snapshot.

Type:	float

tags¶

A list of tags for the snapshot.

Type:	list

classmethod list(**kwargs)¶

Return a list of snapshot instances.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20)
Returns:	A list of snapshot instances.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listDropletSnapshots(**kwargs)¶

Return a list of droplet snapshots.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20)
Returns:	A list of droplet snapshots.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listVolumeSnapshots(**kwargs)¶

Return a list of volume snapshots.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20)
Returns:	A list of volume snapshots.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

SSH Keys¶

class dopyapi.sshkeys.SSHKey(data=None)¶

This class represents SSHKeys in Digital Ocean.

SSHKeys are used to embed public keys at droplet creation.

id¶

A unique identifier for the key.

Type:	int

fingerprint¶

The fingerprint value generated from the public key.

Type:	str

public_key¶

The entire public key as a string.

Type:	str

name¶

A human readable name for the key.

Type:	str

classmethod list(**kwargs)¶

Return a list of SSHKey instances.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20)
Returns:	A list of SSHKey instances.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

Tags¶

class dopyapi.tags.Tag(data=None)¶

This class represents tags on Digital Ocean.

A tag is applied on resources and helps to group them and facilates lookups and actions on them.

name¶

A name for the tag.

Type:	str

resources¶

An object that contains keys and values for all resources tagged with this tag with count and last_tagged_uri attribute.

Type:	dictionary

classmethod list(**kwargs)¶

Return a list of tag instances.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20)
Returns:	A list of tag instances.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

tag(resources)¶

Tag resources with this tag.

Parameters:	resources – A list of objects that represents Digital Ocean resources.
Returns:	The response from Digital Ocean API.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

unTag(resources)¶

remove this tag from resources with.

Parameters:	resources – A list of objects that represents Digital Ocean resources.
Returns:	An object with key of “status” and value “deleted”.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

Volumes¶

class dopyapi.volumes.Volume(data=None)¶

This class represents a single Block Storage volume in Digital Ocean.

A volume appears as locally attached disk to a droplet that can be formatted: by the operating system, it can have sizes from 1GB up to 16TB.

id¶

The unique identifier for the Block Storage volume.

Type:	str

region¶

The region where the volume is located.

Type:	Region

droplet_ids¶

A list that contains the droplet IDs for droplets where this volume is attached to, so far a volume can be attached only to a single droplet.

Type:	list

name¶

A human readable name for the volume.

Type:	str

description¶

An optional description for the volume.

Type:	str

size_gigabytes¶

The size of volume in GB.

Type:	int

created_at¶

The time when the volume was created.

Type:	datetime

filesystem_type¶

The type of filesystem currently in-use on the volume.

Type:	str

filesystem_label¶

The label currently applied to the filesystem.

Type:	str

tags¶

A list of Tags the volume has been tagged with.

Type:	list

classmethod delete_by_name(name, region)¶

Delete a volume by name and region name

This method is used to delete a volume by its name and in which: region it exists.

Parameters:	name (str) – The name of the volume. region (str, Region) – The name of region or the region object.
Returns:	A dictionary with one key “status” and value “deleted”.
Return type:	dict
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422. `ClientForbiddenError` – This is raised when the status code is 403

classmethod get_by_name(name, region)¶

Get a volume by specifying a region and name

This method will return a volume with the given name and the used: region, volumes with the same name could exist in different regions.

Parameters:	name (str) – The name of the volume. region (str, Region) – The name of region or the region object.
Returns:	The volume object found
Return type:	Volume
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod list(**kwargs)¶

Return a list of volume instances.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20)
Returns:	A list of volume instances.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

classmethod listByName(name, **kwargs)¶

Return a list of volume instances by name.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20) name (str) – The pattern for volumes name.
Returns:	A list of volume instances by name.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listSnapshots(**kwargs)¶

Return a list of volume snapshots.

Parameters:	page (int) – The page we want to fetch. (default 1) per_page (int) – The number of snapshot instances in a single page. (default 20)
Returns:	A list of volume snapshots.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

snapshot(name, tags=[])¶

Take a snapshot of a volume.

This method is used to take a volume snapshot.

Parameters:	name (str) – The name of snapshot. tags (list) – A list of tags for the snapshot (default [])
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400, 422, 409 and 429. `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

VPC¶

class dopyapi.vpcs.VPC(data=None)¶

This class is used to manage Virtual Private Clouds (VPCs) in Digital Ocean.

VPCs allow users to create separate private networks for: their resources where resources in one VPC cannot communicate with resources in another VPC.

id¶

A unique ID that can be used to identify and reference the VPC.

Type:	str

urn¶

The uniform resource name (URN) for the VPC.

Type:	str

name¶

The name of the VPC. Must be unique and may only contain alphanumeric characters, dashes, and periods.

Type:	str

region¶

The slug identifier for the region where the VPC will be created.

Type:	str

ip_range¶

The range of IP addresses in the VPC in CIDR notation.

Type:	str

description¶

A free-form text field for describing the VPC’s purpose. It may be a maximum of 255 characters.

Type:	str

default¶

A boolean value indicating whether or not the VPC is the default one for the region.

Type:	bool

created_at¶

A time value given in ISO8601 combined date and time format.

Type:	datetime.datetime

classmethod list(**kwargs)¶

This method returns a list of VPCs as defined by its arguments

Parameters:	page (int) – The page to fetch from all VPCs (defaults 1) per_page (int) – The number of VPCs per a single page (defaults 20)
Returns:	A list of VPC objects
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404

listMembers()¶

Return a list of members with this VPC

The list contains dictionaries each one with these keys:

urn: The Uniform Resource Name for the resource used.

name: The name of resource

created_at: A time value given in ISO8601 combined date and time format that represents when the resource was created.

Parameters:	page (int) – The page to fetch from all VPCs (defaults 1) per_page (int) – The number of VPCs per a single page (defaults 20)
Returns:	A list of dictionaries.
Return type:	list
Raises:	`DOError` – This is raised when the status code is 500 `ClientError` – This is raised when the status code is 400 or 422 `ClientForbiddenError` – This is raised when the status code is 403 `ResourceNotFoundError` – This is raised when the status code is 404