digitaloceanobjects 0.0.15

digitaloceanobjects, represents all digital ocean services as objects, hiding all those horrible api calls.

digitalocean objects (pip3 install digitaloceanobjects)

everyone: I wish, for once, to just have a simple object oriented experience with the api.

digitaloceanobjects:

Please visit GitHub page for documentation that has navigation that works.

Table of Contents

• How to install
• Configurations
• OMG OMG SHOW ME SHOW ME HOW... NOW!!!
• Blocking Wonderfull Blocking
• Account
  • Account Manager
    • Retrieve Account Information
• Sizes
  • Size Manager
    • Retrieve Sizes
  • Size Object
• Regions
  • Region Manager
    • Retrieve All Regions
  • Region Object
• SSH Keys
  • SSH Key Manager
    • Retrieve All SSH Keys
    • Create New Key
    • Retrieve SSH Key Using ID
  • SSH Key Object
    • Update SSH Key Name
    • Delete SSH Key
• Droplets
  • Droplet Manager
    • Create New Droplet
    • Retrieve Droplet By ID
    • Retrieve Droplets By Name
    • Retrieve All Droplets
    • Retrieve Droplets With ANY tags
    • Retrieve Droplets With ALL tags
    • Retrieve Droplets With ONLY tags
    • Delete Droplets With ANY tags
    • Delete Droplets With ALL tags
    • Delete Droplets With ONLY tags
    • Delete Droplet By ID
  • Droplet Object
    • Reboot
    • Power Cycle
    • Shutdown
    • Power Off
    • Power On
    • Rebuild
    • Rename
    • Create Snapshot
    • Retrieve Snapshots
    • Retrieve Snapshot By ID
    • Retrieve Associated Volumes
    • Retrieve Associated Volume Snapshots
    • Attach A Volume
    • Detach A Volume
    • Restore Droplet
    • Resize Droplet
    • Delete Droplet
• Block Storage (Volumes)
  • Volume Manager
    • Create New Volume
    • Retrieve All Volumes
    • Retrieve All Volumes By Name
    • Retrieve Volume By ID
    • Retrieve Volume By Name And Region
    • Retrieve Volumes With ANY Tags
    • Retrieve Volumes With ALL Tags
    • Retrieve Volumes With ONLY Tags
    • Delete Volume By ID
    • Delete Volume By Name And Region
    • Delete Volumes With ANY Tags
    • Delete Volumes With ALL Tags
    • Delete Volumes With ONLY Tags
  • Volume Object
    • Create Snapshot
    • Retrieve Snapshots
    • Detach From Droplets
    • Resize Volume
• Snapshots
  • Snapshot Manager
    • Retrieve All Snapshots
    • Retrieve All Droplet Snapshots
    • Retrieve All Volume Snapshots
    • Retrieve Snapshot By ID
  • Snapshot Object
    • Delete Snapshot
• Floating IPs
  • Floating IP Manager
    • Retrieve All Floating IPs
    • Create New Floating IP
    • Create Region Reserve IP
    • Retrieve Floating IP
  • Floating IP Object
    • Delete Floating IP
    • Unassign Floating IP
    • Retrieve All IP Actions
    • Retrieve Existing IP Action
• Actions
  • Action Manager
    • Retrieve All Actions
    • Retrieve Action
  • Action Object
• Exceptions
  • Droplet Exceptions
  • Volume Exceptions
  • Snapshot Exceptions
  • Action Exceptions
  • Region Exceptions
  • Floating IP Exceptions
  • SSH Key Exceptions

How to install

You can install digitaloceanobjects using pip3

pip3 install -U digitaloceanobjects

or if you prefer install from a cloned git hub repo, from the root of the repo:

python3 setup.py sdist
twine check dist/*
pip3 install -e ./

⬆ back to top

Configurations

Token

Set the DIGITALOCEAN_ACCESS_TOKEN environment variable with your api key.

export DIGITALOCEAN_ACCESS_TOKEN='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

api connection settings

You don't need to look too deeply here, this is for information only.

digitalocean-objects is powered by a baserestapi class from the following project.

https://github.com/zorani/cloudapi/blob/main/cloudapi/baserestapi.py

digitalocean-objects/digitaloceanapi/digitaloceanapiconnection.py inherits baserestapi, baseresapi takes care of all the tricky rate limiting.

Inside /digitaloceanapiconnection.py you will find a 'callrateperhour' variable set to the current digital ocean limit of 5000. digitalocean-objects converts 'callrateperhour' to seconds between requests.

You will also see the following variables.

geometric_delay_multiplier: If a request fails, the 'seconds between requests' is increased by multiplying by this number.

maximum_geometric_delay_multiplicaiton: How many times should you increase the 'seconds between requests' before considering it a fail.

maximum_failed_attempts: a failed attempt is put to the back of an internal queue for a retry. how many failed attempts are allowed before returning the response with failure codes and content.

        BaseRESTAPI.__init__(
            self,
            baseurl="https://api.digitalocean.com",
            callrateperhour=5000,
            geometric_delay_multiplier=2,
            maximum_geometric_delay_multiplications=6,
            maximum_failed_attempts=3,
        )

⬆ back to top

OMG OMG SHOW ME SHOW ME HOW NOW

Okay!! Okay!! Here is a quick start example!

Look how easy it is to work with digitaloceanobjects...

...read the code comments...

#!/usr/bin/env python3

from digitaloceanobjects import Droplet, DropletManager
from digitaloceanobjects import Volume, VolumeManager

#Create a droplet manager, to you know... manage your droplets.
droplet_manager = DropletManager()

#Create a new droplet.
my_brand_new_droplet = droplet_manager.create_new_droplet(
    name="test-droplet",
    region="ams3",
    size="s-1vcpu-1gb",
    image="ubuntu-16-04-x64",
    tags=["digitalocean", "objects", "are", "great"],
)

#What? Done already?
#Yup... now output the droplet details.
print(type(my_brand_new_droplet))
print(my_brand_new_droplet.attributes)

#Want to attache a volume? No problem...

#Create a volume manager.
volume_manager = VolumeManager()

#You'll need a volume, so lets create a new volume.
my_brand_new_volume = volume_manager.create_new_volume(
    size_gigabytes=10,
    name="test-volume",
    region="ams3",
    description="BlockStoreFor Examples",
    filesystem_type="ext4",
    filesystem_label="example",
    tags=["is", "it", "really", "this", "easy"],
)

#Well... damn that was easy. Peek at the volume object and the attributes. Nice.
print(type(my_brand_new_volume))
print(my_brand_new_volume.attributes)

#So, now just ask your droplet to attach your new volume.
my_brand_new_droplet.attach_a_volume(my_brand_new_volume)

#Still don't beleive how easy this was? Check the droplet attributes, you will now have a volume id attached to it.
print(my_brand_new_droplet.attributes.volume_ids)

Hope you're happy...

... now read the rest of the documentation to see what other amazing things you can do!

⬆ back to top

Blocking Wonderfull Blocking

Did you notice in the quick start example above we didn't at any point check to see if the droplet, or the volume were ready and available?

Well... that's because digitaloceanobjects is 'blocking', it waits for an operation on digital ocean to complete before returning.

You can code away, without any worries.

If you want to setup multiple droplets concurrently you should thread your droplet set up script so you're not waiting on independent services.

Account

Account Manager

from digitaloceanobjects import AccountManager
account_manager=AccountManager()

Retrieve Account Information

droplet_limit = account_manager.droplet_limit()

floating_ip_limit = account_manager.floating_ip_limit()

volume_limit = account_manager.volume_limit()

email = account_manager.email()

email_verified = account_manager.email_verified()

uuid = account_manager.uuid()

status = account_manager.status()

status_message = account_manager.status_message()

⬆ back to top

Sizes

from digitaloceanobjects import Size, SizeManager

Size Manager

size_manager=SizeManager()

Retrieve Sizes

list_of_size_objects=size_manager.retrieve_sizes()

Size Object

class Size:
    def __init__(self):
        self.attributes = SizeAttributes()

@dataclass
class SizeAttributes:
    slug: str = None
    available: bool = None
    transfer: float = None
    price_monthly: float = None
    price_hourly: float = None
    memory: int = None
    vcpus: int = None
    disk: int = None
    regions: list = field(default_factory=list)
    description: str = None

⬆ back to top

Regions

from digitaloceanobjects import Region, RegionManager

Region Manager

region_manager = RegionManager()

Retrieve All Regions

list_of_region_objects = region_manager.retrieve_all_regions()

Region Object

class Region:
    def __init__(self):
        self.attributes = RegionAttributes()

@dataclass
class RegionAttributes:
    slug: str = None
    name: str = None
    sizes: list = field(default_factory=list)
    available: bool = None
    features: list = field(default_factory=list)

⬆ back to top

SSH Keys

from digitaloceanobjects import SSHkey, SSHkeyManager

SSH Key Manager

sshkey_manager = SSHkeyManager()

Retrieve All SSH Keys

list_of_sshkey_objects=sshkey_manager.retrieve_all_sshkeys()

Create New Key

sshkey_object=sshkey_manager.create_new_key(name:str, public_key:str)

Retrieve SSH Key Using ID

sshkey_object=sshkey_manager.retrieve_sshkey_with_id(id:int)

SSH Key Object

sshkey_object=SSHkey()

class SSHkey:
    def __init__(self):
        self.attributes = SSHkeyAttributes()

@dataclass
class SSHkeyAttributes:
    id: str = None
    fingerprint: str = None
    public_key: str = None
    name: str = None

Update SSH Key Name

sshkey_object.update_name(name:str)

Delete SSH Key

sshkey_object.delete()

⬆ back to top

Droplets

from digitaloceanobjects import Droplet, DropletManager

Droplet Manager

droplet_manager = DropletManager()

Create New Droplet

droplet_object = droplet_manager.create_new_droplet(
						name="example.com",
						region="nyc3",
						size="s-1vcpu-1gb",
						image="ubuntu-16-04-x64",
						ssh_keys=[],
						backups=False,
						ipv6=True,
						user_data=None,
						private_networking=None,
						volumes=None,
						tags=["bananas"],
					)

Retrieve Droplet By ID

droplet_object = droplet_manager.retrieve_droplet_by_id(id:int)

Retrieve Droplets By Name

droplet_object = droplet_manager.retrieve_droplet_by_name(name:str)

Retrieve All Droplets

list_of_droplet_objects = droplet_manager.retrieve_all_droplets()

Retrieve Droplets With ANY tags

list_of_droplet_objects = droplet_manager.retrieve_droplets_with_any_tags(tag:list)

Retrieve Droplets With ALL tags

list_of_droplet_objects = droplet_manager.retrieve_droplets_with_all_tags(tag:list)

Retrieve Droplets With ONLY tags

list_of_droplet_objects = droplet_manager.retrieve_droplets_with_only_tags(tag:list)

Delete Droplets With ANY tags

droplet_manager.delete_droplets_with_any_tags(tag:list)

Delete Droplets With ALL tags

droplet_manager.delete_droplets_with_all_tags(tag:list)

Delete Droplets With ONLY tags

droplet_manager.delete_droplets_with_only_tags(tag:list)

Delete Droplet By ID

droplet_manager.delete_droplet_by_id(id:int)

⬆ back to top

Droplet Object

droplet_object=Droplet()

class Droplet:
    def __init__(self, status=None):
        self.attributes = DropletAttributes()
        self.attributes.status = status
        self.deleted=False
        ...

@dataclass
class DropletAttributes:
    id: int = None
    name: str = None
    memory: int = None
    vcpus: int = None
    disk: int = None
    locked: bool = None
    created_at: str = None
    status: str = None
    backup_ids: list = field(default_factory=list)
    snapshot_ids: list = field(default_factory=list)
    features: list = field(default_factory=list)
    region: object = field(default_factory=list)
    image: object = field(default_factory=list)
    size: object = field(default_factory=list)
    size_slug: str = None
    networks: object = field(default_factory=list)
    kernel: object = field(default_factory=list)
    next_backup_window: object = field(default_factory=list)
    tags: list = field(default_factory=list)
    volume_ids: list = field(default_factory=list)
    vpc_uuid: list = field(default_factory=list)

Reboot

droplet_object.reboot()

Power Cycle

droplet_object.powercycle()

Shutdown

droplet_object.shutdown()

Power Off

droplet_object.poweroff()

Power On

droplet_object.poweron()

Rebuild

droplet_object.rebuild(img:str)

Rename

droplet_object.rename(name:str)

Create Snapshot

dropletsnapshot_object = droplet_object.createsnapshot(name:str)

class DropletSnapshot:
    def __init__(self):
        self.attributes = DropletSnapshotAttributes()

@dataclass
class DropletSnapshotAttributes:
    id: int = None
    name: str = None
    distribution: str = None
    slug: str = None
    public: bool = None
    regions: list = field(default_factory=list)
    created_at: str = None
    min_disk_size: int = None
    type: str = None
    size_gigabytes: float = None

Retrieve Snapshots

list_of_dropletsnapshot_objects = droplet_object.retrieve_snapshots()

Retrieve Snapshot By ID

Only searches snapshots associated to droplet.

dropletsnapshot_object = droplet_object.retrieve_snapshot_by_id(id:int)

Retrieve Associated Volumes

list_of_volume_objects = droplet_object.retrieve_associated_volumes()

Retrieve Associated Volume Snapshots

list_of_volume_snapshot_objects = droplet_object.retrieve_associated_volume_snapshots()

Attach A Volume

droplet_object.attach_a_volume(target_volume:Volume)

Detach A Volume

droplet_object.detach_a_volume(target_volume:Volume)

Restore Droplet

droplet_object.restore_droplet(image_id:int)

Resize Droplet

If you set disk=False only the RAM will be increased. If you set disk=True the disk size will be upgraded, and you will not be able to shrink your droplet down to it's previous RAM size.

droplet_object.resize_droplet(
				slug_size='s-1vcpu-2gb',
				disk_resize=False
				)

Delete Droplet

droplet_object.delete()

Deletes droplet from your account. Sets droplet_object.deleted=True so object methods will no longer work.

⬆ back to top

Block Storage (Volumes)

from digitaloceanobjects import Volume, VolumeManager

Volume Manager

volume_manager = VolumeManager()

Create New Volume

volume_object = volume_manager.create_new_volume(
	        size_gigabytes=10,
	        name="testingavolume",
	        region="ams3",
	        description="BlockStoreExample",
	        filesystem_type="ext4",
	        filesystem_label="example",
	        tags=["banana"],
	    )

Retrieve All Volumes

list_of_volume_objects=volume_manager.retrieve_all_volumes()

Retrieve All Volumes By Name

list_of_volume_objects=volume_manager.retrieve_all_volumes_by_name(name:str)

Retrieve Volume By ID

volume_object=volume_manager.retrieve_volume_by_id(id:int)

Retrieve Volume By Name And Region

volume_object=volume_manager.retrieve_volume_by_name_region(
											name:str,
											region:str
										)

Retrieve Volumes With ANY Tags

list_of_volume_objects=volume_manager.retrieve_volumes_with_any_tags(tag:list)

Retrieve Volumes With ALL Tags

list_of_volume_objects=volume_manager.retrieve_volumes_with_all_tags(tag:list)

Retrieve Volumes With ONLY Tags

list_of_volume_objects=volume_manager.retrieve_volumes_with_only_tags(tag:list)

Delete Volume By ID

volume_manager.delete_volumes_by_id(id:int)

Delete Volume By Name And Region

volume_manager.delete_volume_by_name_region(
								name:str,
								region:str
							)

Delete Volumes With ANY Tags

volume_manager.delete_volumes_with_any_tags(tag:list)

Delete Volumes With ALL Tags

volume_manager.delete_volumes_with_all_tags(tag:list)

Delete Volumes With ONLY Tags

volume_manager.delete_volumes_with_only_tags(tag:list)

⬆ back to top

Volume Object

volume_object=Volume()

class Volume:
    def __init__(self):
        self.attributes = VolumeAttributes()
        self.deleted=False
        ...

@dataclass
class VolumeAttributes:
    id: str = None
    region: object = field(default_factory=list)
    droplet_ids: list = field(default_factory=list)
    name: str = None
    description: str = None
    size_gigabytes: int = None
    created_at: str = None
    filesystem_type: str = None
    filesystem_label: str = None
    tags: list = field(default_factory=list)

Create Snapshot

snapshot_object=volume_object.create_snapshot(
						name:str,
						tags:list
					)

Retrieve Snapshots

list_of_snapshot_objects=volume_object.retrieve_snapshots()

Detach From Droplets

volume_object.detach_from_droplets()

Resize Volume

volume_object.resize(size_gigabytes:int)

⬆ back to top

Snapshots

from digitaloceanobjects import Snapshot, SnapshotManager

Snapshot Manager

snapshot_manager=SnapshotManager()

Retrieve All Snapshots

list_of_snapshot_objects=snapshot_manager.retrieve_all_snapshots()

Retrieve All Droplet Snapshots

list_of_snapshot_objects=snapshot_manager.retrieve_all_droplet_snapshots()

Retrieve All Volume Snapshots

list_of_snapshot_objects=snapshot_manager.retrieve_all_volume_snapshots()

Retrieve Snapshot By ID

snapshot_object=snapshot_manager.retrieve_snapshots_id(id:int)

⬆ back to top

Snapshot Object

snapshot_object=Snapshot()

class Snapshot:
    def __init__(self):
        self.attributes = SnapshotAttributes()
		...

@dataclass
class SnapshotAttributes:
    id: str = None
    name: str = None
    created_at: str = None
    regions: list = field(default_factory=list)
    resource_id: str = None
    resource_type: str = None
    min_disk_size: int = None
    size_gigabytes: float = None
    tags: list = field(default_factory=list)

Delete Snapshot

snapshot_object.delete()

⬆ back to top

Floating IPs

from digitaloceanobjects import FloatingIP, FloatingIPManager

Floating IP Manager

floatingip_manager=FloatingIPManager()

Retrieve All Floating IPs

list_of_floatingip_objects=floatingip_manager.retrieve_all_floating_ips()

Create New Floating IP

Creates a floating IP and attaches it straight to the mentioned droplet.

floatingip_object=floatingip_manager.create_new_floating_ip(droplet_object:Droplet)

Create Region Reserve IP

floatingip_object=floatingip_manager.reserve_ip_for_region(region_slug:str)

Retrieve Floating IP

floatingip_object=floatingip_manager.retrieve_floating_ip(ip:int)

⬆ back to top

Floating IP Object

floatingip_object=FloatingIP()

class FloatingIP:
    def __init__(self):
        self.attributes = FloatingIPAttributes()
		...

@dataclass
class FloatingIPAttributes:
    ip: str = None
    region: object = None
    droplet: object = None
    locked: bool = None

Delete Floating IP

floatingip_object.delete()

Unassign Floating IP]

floatingip_object.unassign()

Retrieve All IP Actions

list_of_action_objects=floatingip_object.retrieve_all_actions()

Retrieve Existing IP Action

action_object=floatingip_object.retrieve_existing_actions(action_id:int)

⬆ back to top

Actions

from digitaloceanobjects import Action, ActionManager

Action Manager

action_manager=ActionManager()

Retrieve All Actions

list_of_action_objects=action_manager.retrieve_all_actions()

Retrieve Action

action_object=action_manager.retrieve_action(action_id:int)

Action Object

action_object=Action()

class Action:
    def __init__(self, action_attributes: ActionAttributes):
        self.attributes = action_attributes
		'''

@dataclass
class ActionAttributes:
    id: int = None
    status: str = None
    type: str = None
    started_at: str = None
    completed_at: str = None
    resource_id: int = None
    resource_type: str = None
    region: object = None
    region_slug: str = None

⬆ back to top

Exceptions

Droplet Exceptions

ErrorDropletNotFound
ErrorDropletNameContainsInvalidChars
ErrorDropletSlugSizeNotFound
ErrorDropletResizeDiskError
ErrorAccountDropletLimitReached
ErrorDropletAttachedVolumeCountAlreadAtLimit

Volume Exceptions

ErrorVolumeAlreadyExists
ErrorVolumeNotFound
ErrorVolumeResizeValueTooLarge
ErrorVolumeResizeDirection
ErrorAccountVolumeLimitReached

Snapshot Exceptions

ErrorSnapshotNotFound

Action Exceptions

ErrorActionDoesNotExists
ErrorActionFailed

Region Exceptions

ErrorNotSameRegion
ErrorRegionDoesNotExist

Floating IP Exceptions

ErrorAccountFloatingIPLimitReached
ErrorFloatingIPDoesNotExists
ErrorDropletAlreadyHasFloatingIP

SSH Key Exceptions

ErrorSSHkeyDoesNotExists

⬆ back to top