digitaloceanobjects, represents all digital ocean services as objects, hiding all those horrible api calls.
Project description
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
- Sizes
- Regions
- SSH Keys
- Droplets
- 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
- Volume Manager
- Snapshots
- Floating IPs
- Actions
- 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 ./
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,
)
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!
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()
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
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)
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()
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)
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.
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)
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)
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)
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()
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)
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)
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
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for digitaloceanobjects-0.0.15.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 33e6a0b1536d89077fd82bc3ca99a23a274c85887625e4518d535d20f663c00c |
|
MD5 | 566cbeb18240844bf8e6a3114544ed34 |
|
BLAKE2b-256 | b2504a441017b8a64ec75a75e7f4bf6bff6a4f88112faed14ffc015a7230b3cd |