Developer Interface

This part of the documentation covers all the interfaces of Pontoon.

Library Module

pontoon.lib is the main entry point for using the library as a developer.

digitalocean API to manage droplets

Manager Class

class pontoon.lib.Manager(*args, **kwargs)[source]
_Manager__deal_with_pagination(url, data, params)

Perform multiple calls in order to have a full list of elements when the API are “paginated”. (content list is divided in more than one page)

get_account()[source]

Returns an Account object.

get_action(action_id)[source]

Return an Action object by a specific ID.

get_all_actions()[source]

This functions returns a list of Action objects.

get_all_domains()[source]

This function returns a list of Domain object.

get_all_droplets()[source]

This function returns a list of Droplet object.

get_all_floating_ips()[source]

This function returns a list of FloatingIP objects.

get_all_images()[source]

This function returns a list of Image objects containing all available DigitalOcean images, both public and private.

get_all_regions()[source]

This function returns a list of Region object.

get_all_sizes()[source]

This function returns a list of Size object.

get_all_sshkeys()[source]

This function returns a list of SSHKey object.

get_app_images()[source]

This function returns a list of Image objectobjects representing public DigitalOcean ‘One-Click’ application images.

get_data(*args, **kwargs)[source]

Customized version of get_data to perform __check_actions_in_data.

The default amount of elements per page defined is 200 as explained here: https://github.com/koalalorenzo/python-digitalocean/pull/78

get_distro_images()[source]

This function returns a list of Image objects representing public base distribution images.

get_domain(domain_name)[source]

Return a Domain by its domain_name

get_droplet(droplet_id)[source]

Return a Droplet by its ID.

get_floating_ip(ip)[source]

Returns a of FloatingIP object by its IP address.

get_global_images()[source]

This function returns a list of Image objects representing public DigitalOcean images (e.g. base distribution images and ‘One-Click’ applications).

get_image(image_id)[source]

Return a Image by its ID.

get_images(private=False, type=None)[source]

This function returns a list of Image object.

get_my_images()[source]

This function returns a list of Image objects representing private DigitalOcean images (e.g. snapshots and backups).

get_ssh_key(ssh_key_id)[source]

Return a SSHKey object by its ID.

Droplet Class

class pontoon.lib.Droplet(*args, **kwargs)[source]

“Droplet management

Attributes accepted at creation time:
name: str - name size_slug: str - droplet size image: str - image name to use to create droplet region: str - region ssh_keys: [str] - list of ssh keys backups: bool - True if backups enabled ipv6: bool - True if ipv6 enabled private_networking: bool - True if private networking enabled user_data: str - arbitrary data to pass to droplet
Attributes returned by API:

id: int - droplet id memory: str - memory size vcpus: int - number of vcpus disk: int - disk size in GB status: str - status locked: bool - True if locked created_at: str - creation date in format u‘2014-11-06T10:42:09Z’ status: str - status, e.g. ‘new’, ‘active’, etc networks: dict - details of connected networks kernel: dict - details of kernel backup_ids: [int] - list of ids of backups of this droplet snapshot_ids: [int] - list of ids of snapshots of this droplet action_ids: [int] - list of ids of actions features: [str] - list of enabled features. e.g.

[u’private_networking’, u’virtio’]
min_size: str - minumum size of droplet that can bew created from a
snapshot of this droplet

image: dict - details of image used to create this droplet ip_address: str - public ip addresses private_ip_address: str - private ip address ip_v6_address: [str] - list of ipv6 addresses assigned end_point: str - url of api endpoint used

_Droplet__get_ssh_keys_id_or_fingerprint()

Check and return a list of SSH key IDs or fingerprints according to DigitalOcean’s API. This method is used to check and create a droplet with the correct SSH keys.

_perform_action(params, return_dict=True)[source]

Perform a droplet action.

Args:
params - dict : parameters of the action
Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

change_kernel(kernel, return_dict=True)[source]

Change the kernel to a new one

Args:
kernel : instance of digitalocean.Kernel.Kernel
Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

create(*args, **kwargs)[source]

Create the droplet with object properties.

Note: Every argument and parameter given to this method will be assigned to the object.

destroy()[source]

Destroy the droplet

Returns dict

disable_backups(return_dict=True)[source]

Disable automatic backups

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

enable_backups()[source]

Enable automatic backups (Not yet implemented in APIv2)

enable_ipv6(return_dict=True)[source]

Enable IPv6 on an existing Droplet where available.

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

enable_private_networking(return_dict=True)[source]

Enable private networking on an existing Droplet where available.

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

get_action(action_id)[source]

Returns a specific Action by its ID.

Args:
action_id: int - id of action
get_actions()[source]

Returns a list of Action objects This actions can be used to check the droplet’s status

get_data(*args, **kwargs)[source]

Customized version of get_data to perform __check_actions_in_data

get_events()[source]

A helper function for backwards compatability. Calls get_actions()

get_kernel_available()[source]

Get a list of kernels available

classmethod get_object(api_token, droplet_id, mocked)[source]

Class method that will return a Droplet object by ID.

Args:
api_token: str - token droplet_id: int - droplet id mocked: bool - mocked
get_snapshots()[source]

This method will return the snapshots/images connected to that specific droplet.

load()[source]

Fetch data about droplet - use this instead of get_data()

power_cycle(return_dict=True)[source]

restart the droplet

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

power_off(return_dict=True)[source]

restart the droplet

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

power_on(return_dict=True)[source]

Boot up the droplet

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

reboot(return_dict=True)[source]

restart the droplet

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

rebuild(image_id=None, return_dict=True)[source]

Restore the droplet to an image ( snapshot or backup )

Args:
image_id : int - id of image
Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

rename(name, return_dict=True)[source]

Rename the droplet

Args:
name : str - new name
Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

reset_root_password(return_dict=True)[source]

reset the root password

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

resize(new_size_slug, return_dict=True, disk=True)[source]

Resize the droplet to a new size slug. https://developers.digitalocean.com/documentation/v2/#resize-a-droplet

Args:
new_size_slug: str - name of new size
Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

disk - bool : If a permanent resize, with disk changes included.

Returns dict or Action

restore(image_id, return_dict=True)[source]

Restore the droplet to an image ( snapshot or backup )

Args:
image_id : int - id of image
Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

shutdown(return_dict=True)[source]

shutdown the droplet

Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.

Returns dict or Action

take_snapshot(snapshot_name, return_dict=True, power_off=False)[source]

Take a snapshot!

Args:
snapshot_name: str - name of snapshot
Optional Args:
return_dict - bool : Return a dict when True (default),
otherwise return an Action.
power_off - bool : Before taking the snapshot the droplet will be
turned off with another API call. It will wait until the droplet will be powered off.

Returns dict or Action

Account Class

class pontoon.lib.Account(*args, **kwargs)[source]
classmethod get_object(api_token, mocked)[source]

Class method that will return an Account object.

Action Class

class pontoon.lib.Action(*args, **kwargs)[source]
classmethod get_object(api_token, action_id, mocked)[source]

Class method that will return a Action object by ID.

wait(update_every_seconds=1)[source]

Wait until the action is marked as completed or with an error. It will return True in case of success, otherwise False.

Optional Args:
update_every_seconds - int : number of seconds to wait before
checking if the action is completed.

Domain Class

class pontoon.lib.Domain(*args, **kwargs)[source]
create()[source]

Create new domain

create_new_domain_record(*args, **kwargs)[source]

Create new domain record. https://developers.digitalocean.com/#create-a-new-domain-record

Args:

@type The record type (A, MX, CNAME, etc). @name The host name, alias, or service being defined by the record @data Variable data depending on record type.

Optional Args:

@priority The priority of the host @port The port that the service is accessible on @weight The weight of records with the same priority

destroy()[source]

Destroy the domain by name

classmethod get_object(api_token, domain_name, mocked)[source]

Class method that will return a Domain object by ID.

get_records(params=None)[source]

Returns a list of Record objects

load()[source]

FloatingIP Class

class pontoon.lib.FloatingIP(*args, **kwargs)[source]
assign(droplet_id)[source]

Assign a FloatingIP to a Droplet.

Args:
droplet_id: int - droplet id
create(*args, **kwargs)[source]

Creates a FloatingIP and assigns it to a Droplet.

Note: Every argument and parameter given to this method will be assigned to the object.

Args:
droplet_id: int - droplet id
destroy()[source]

Destroy the FloatingIP

classmethod get_object(api_token, ip, mocked)[source]

Class method that will return a FloatingIP object by its IP.

Args:
api_token: str - token ip: str - floating ip address
load()[source]

Load the FloatingIP object from DigitalOcean.

Requires self.ip to be set.

reserve(*args, **kwargs)[source]

Creates a FloatingIP in a region without assigning it to a specific Droplet.

Note: Every argument and parameter given to this method will be assigned to the object.

Args:
region_slug: str - region’s slug (e.g. ‘nyc3’)
unassign()[source]

Unassign a FloatingIP.

Image Class

class pontoon.lib.Image(*args, **kwargs)[source]
destroy()[source]

Destroy the image

classmethod get_object(api_token, image_id, mocked)[source]

Class method that will return an Image object by ID.

rename(new_name)[source]

Rename an image

transfer(new_region_slug)[source]

Transfer the image

Kernel Class

class pontoon.lib.Kernel(*args, **kwargs)[source]

Record Class

class pontoon.lib.Record(domain_name=None, *args, **kwargs)[source]
create()[source]

Create a record for a domain

destroy()[source]

Destroy the record

classmethod get_object(api_token, domain, record_id)[source]

Class method that will return a Record object by ID and the domain.

save()[source]

Save existing record

Region Class

class pontoon.lib.Region(*args, **kwargs)[source]

SSHKey Class

class pontoon.lib.SSHKey(*args, **kwargs)[source]
create()[source]

Create the SSH Key

destroy()[source]

Destroy the SSH Key

edit()[source]

Edit the SSH Key

classmethod get_object(api_token, ssh_key_id, mocked)[source]

Class method that will return a SSHKey object by ID.

load()[source]

Load the SSHKey object from DigitalOcean.

Requires either self.id or self.fingerprint to be set.

load_by_pub_key(public_key)[source]

This method will laod a SSHKey object from DigitalOcean from a public_key. This method will avoid problem like uploading the same public_key twice.

Size Class

class pontoon.lib.Size(*args, **kwargs)[source]

UI module

This module handles all output for the CLI, as well as some filesystem interactions. This is the only location outside of tests where the print statement is invoked directly.

pontoon.ui.ask(question)[source]

Present a question with freeform input on an interactive prompt

pontoon.ui.ask_yesno(question)[source]

Present a string as a yes/no question on an interactive prompt

pontoon.ui.box(text, decor='*', decor_x=None, decor_y=None, boxwidth=60, borderwidth=2)[source]

Create a formatted textbox for highlighting important information

pontoon.ui.filename_from_path(path)[source]

Get a filename from a given path

pontoon.ui.format_droplet_info(machine)[source]

Present Droplet information in a more human parseable format

pontoon.ui.format_event(action)[source]

Present event information in a more human parseable format

pontoon.ui.format_item(item)[source]

Present any item in more human parseable format

pontoon.ui.full_path(path)[source]

Expand a ~/ prefixed path to a full path

pontoon.ui.heading(text, boxwidth=60)[source]

Create a ‘heading’ styled textbox

pontoon.ui.line(length=60, decor='-')[source]

Write a line

pontoon.ui.machine()[source]
pontoon.ui.mask(text, masker='*')[source]

Hide part of a string,

If the input is small, hide the entire string. Otherwise, show only the last few characters.

pontoon.ui.message(text)[source]

Wrapper for the print function

pontoon.ui.notify(text, boxwidth=60)[source]

Create a ‘notification’ styled textbox

pontoon.ui.ordered_dump(data, stream=None, Dumper=<class 'yaml.dumper.Dumper'>, **kwds)[source]
pontoon.ui.ticker()[source]

A loading/waiting indicator.

Sends a ‘.’ to the screen, resets, and sleeps.

pontoon.ui.valid_path(path)[source]

Check whether a given string resolves to a path on the filesystem

pontoon.ui.warning(text, boxwidth=60)[source]

Create a ‘warning’ styled textbox

pontoon.ui.yaml_message(data)[source]

Formats output as ordered YAML

Mocking Module

class pontoon.mocking.Data[source]
pontoon.mocking._raise(ex=None)[source]

Wrapper for exceptions so they can be thrown from inside lambdas

pontoon.mocking.capture_stdout(*args, **kwds)[source]

Captures STDOUT and turns it into an object

pontoon.mocking.event_response()[source]
pontoon.mocking.get_builtins()[source]

Python 2.x and 3.x have different names for accessing builtins

pontoon.mocking.timestamp(hours=0)[source]

Mocked Digital Ocean timestamp

Log Module

pontoon.log.debug(obj)[source]

Exceptions

exception pontoon.exceptions.ConfigureException[source]

An error occurred while processing the configuration file

exception pontoon.exceptions.PontoonException[source]

An ambiguous error occurred while handling the command

Configure Module

The configure module is a collection of methods for handling interaction with some external tools, config files, and for interactive configuration.

pontoon.configure.combined(*args, **kwargs)[source]

Merge configuration defaults with values from config file.

pontoon.configure.create_config(*args, **kwargs)[source]

Create a YAML config file from a dictionary

pontoon.configure.images(credentials)[source]

Retrieve image options

pontoon.configure.logger()[source]

Prepare interface to logging.

pontoon.configure.read_config(*args, **kwargs)[source]

Read a YAML formatted config into a dictionary

pontoon.configure.read_key(*args, **kwargs)[source]

Read a public SSH key from the filesystem

pontoon.configure.regenerate_public_key(*args, **kwargs)[source]

Generate an SSH public key from an existing private key.

pontoon.configure.regions(credentials)[source]

Retrieve region options

pontoon.configure.register_key(*args, **kwargs)[source]

Register an SSH key with Digital Ocean

pontoon.configure.rsa_keygen(*args, **kwargs)[source]

Create a new SSH key

pontoon.configure.sizes(credentials)[source]

Retrieve size options

pontoon.configure.ssh_tools(*args, **kwargs)[source]

Checks for existance of SSH tools required for creating keys.

Command Class

The Command class encapsulates plumbing common to all CLI commands.

class pontoon.command.Command[source]

Base class for CLI commands.

Parses docstrings and initalizes client.

run(override=None)[source]

Run the command specified by the docstring.

Parameters:override – Run a command other than the one specified.