diff --git a/SoftLayer/managers/hardware.py b/SoftLayer/managers/hardware.py index 70aea1ec1..7fe00740f 100644 --- a/SoftLayer/managers/hardware.py +++ b/SoftLayer/managers/hardware.py @@ -26,6 +26,16 @@ class HardwareManager(utils.IdentifierMixin, object): manager to handle ordering. If none is provided, one will be auto initialized. + Example:: + + # Initialize the Manager. + # env variables. These can also be specified in ~/.softlayer, + # or passed directly to SoftLayer.Client() + # SL_USERNAME = YOUR_USERNAME + # SL_API_KEY = YOUR_API_KEY + import SoftLayer + client = SoftLayer.Client() + mgr = SoftLayer.HardwareManager(client) """ def __init__(self, client, ordering_manager=None): self.client = client @@ -46,6 +56,10 @@ def cancel_hardware(self, hardware_id, reason='unneeded', comment='', come from :func:`get_cancellation_reasons`. :param string comment: An optional comment to include with the cancellation. + Example:: + + # Cancels hardware id 1234 + result = mgr.cancel_hardware(hardware_id=1234) """ # Get cancel reason @@ -83,6 +97,12 @@ def list_hardware(self, tags=None, cpus=None, memory=None, hostname=None, hardware. This list will contain both dedicated servers and bare metal computing instances + Example:: + + # Using a custom object-mask. Will get ONLY what is specified + # These will stem from the SoftLayer_Hardware_Server datatype + object_mask = "mask[hostname,monitoringRobot[robotStatus]]" + result = mgr.list_hardware(mask=object_mask) """ if 'mask' not in kwargs: hw_items = [ @@ -152,6 +172,11 @@ def get_hardware(self, hardware_id, **kwargs): :returns: A dictionary containing a large amount of information about the specified server. + Example:: + + object_mask = "mask[id,networkVlans[vlanNumber]]" + # Object masks are optional + result = mgr.get_hardware(hardware_id=1234,mask=object_mask) """ if 'mask' not in kwargs: @@ -219,6 +244,10 @@ def rescue(self, hardware_id): """Reboot a server into the a recsue kernel. :param integer instance_id: the server ID to rescue + + Example:: + + result = mgr.rescue(1234) """ return self.hardware.bootToRescueLayer(id=hardware_id) @@ -230,6 +259,16 @@ def change_port_speed(self, hardware_id, public, speed): True (default) means the public interface. False indicates the private interface. :param int speed: The port speed to set. + + .. warning:: + A port speed of 0 will disable the interface. + + Example:: + + #change the Public interface to 10Mbps on instance 12345 + result = mgr.change_port_speed(hardware_id=12345, + public=True, speed=10) + # result will be True or an Exception """ if public: func = self.hardware.setPublicNetworkInterfaceSpeed @@ -474,6 +513,11 @@ def edit(self, hardware_id, userdata=None, hostname=None, domain=None, :param string domain: valid domain name :param string notes: notes about this particular hardware + Example:: + + # Change the hostname on instance 12345 to 'something' + result = mgr.edit(hardware_id=12345 , hostname="something") + #result will be True or an Exception """ obj = {} @@ -510,6 +554,11 @@ def update_firmware(self, :param bool raid_controller: Update the raid controller firmware. :param bool bios: Update the bios firmware. :param bool hard_drive: Update the hard drive firmware. + + Example:: + + # Check the servers active transactions to see progress + result = mgr.update_firmware(hardware_id=1234) """ return self.hardware.createFirmwareUpdateTransaction( diff --git a/SoftLayer/managers/ssl.py b/SoftLayer/managers/ssl.py index 68e78dbdb..9b698015c 100644 --- a/SoftLayer/managers/ssl.py +++ b/SoftLayer/managers/ssl.py @@ -11,6 +11,18 @@ class SSLManager(object): """Manages SSL certificates. :param SoftLayer.API.Client client: an API client instance + + Example:: + + # Initialize the Manager. + # env variables. These can also be specified in ~/.softlayer, + # or passed directly to SoftLayer.Client() + # SL_USERNAME = YOUR_USERNAME + # SL_API_KEY = YOUR_API_KEY + import SoftLayer + client = SoftLayer.Client() + mgr = SoftLayer.SSLManager(client) + """ def __init__(self, client): @@ -24,6 +36,12 @@ def list_certs(self, method='all'): 'all', 'expired', and 'valid'. :returns: A list of dictionaries representing the requested SSL certs. + Example:: + + # Get all valid SSL certs + certs = mgr.list_certs(method='valid') + print certs + """ ssl = self.client['Account'] methods = { @@ -42,6 +60,11 @@ def add_certificate(self, certificate): :param dict certificate: A dictionary representing the parts of the certificate. See SLDN for more information. + Example:: + + cert = ?? + result = mgr.add_certificate(certificate=cert) + """ return self.ssl.createObject(certificate) @@ -50,6 +73,10 @@ def remove_certificate(self, cert_id): :param integer cert_id: a certificate ID to remove + Example:: + + # Removes certificate with id 1234 + result = mgr.remove_certificate(cert_id = 1234) """ return self.ssl.deleteObject(id=cert_id) @@ -61,6 +88,13 @@ def edit_certificate(self, certificate): :param dict certificate: the certificate to update. + Example:: + + # Updates the cert id 1234 + cert['id'] = 1234 + cert['certificate'] = ?? + result = mgr.edit_certificate(certificate=cert) + """ return self.ssl.editObject(certificate, id=certificate['id']) @@ -69,5 +103,10 @@ def get_certificate(self, cert_id): :param integer cert_id: the certificate ID to retrieve + Example:: + + cert = mgr.get_certificate(cert_id=1234) + print(cert) + """ return self.ssl.getObject(id=cert_id) diff --git a/SoftLayer/managers/vs.py b/SoftLayer/managers/vs.py index 5739ebc5f..ed3f744d8 100644 --- a/SoftLayer/managers/vs.py +++ b/SoftLayer/managers/vs.py @@ -23,6 +23,18 @@ class VSManager(utils.IdentifierMixin, object): manager to handle ordering. If none is provided, one will be auto initialized. + + Example:: + + # Initialize the VSManager. + # env variables. These can also be specified in ~/.softlayer, + # or passed directly to SoftLayer.Client() + # SL_USERNAME = YOUR_USERNAME + # SL_API_KEY = YOUR_API_KEY + import SoftLayer + client = SoftLayer.Client() + mgr = SoftLayer.VSManager(client) + """ def __init__(self, client, ordering_manager=None): @@ -57,18 +69,17 @@ def list_instances(self, hourly=True, monthly=True, tags=None, cpus=None, :returns: Returns a list of dictionaries representing the matching virtual servers - :: + Example:: - # Print out a list of all hourly instances in the DAL05 data center. - # env variables - # SL_USERNAME = YOUR_USERNAME - # SL_API_KEY = YOUR_API_KEY - import SoftLayer - client = SoftLayer.create_client_from_env() + # Print out a list of hourly instances in the DAL05 data center. - mgr = SoftLayer.VSManager(client) - for vsi in mgr.list_instances(hourly=True, datacenter='dal05'): - print vsi['fullyQualifiedDomainName'], vs['primaryIpAddress'] + for vsi in mgr.list_instances(hourly=True, datacenter='dal05'): + print vsi['fullyQualifiedDomainName'], vsi['primaryIpAddress'] + + # Using a custom object-mask. Will get ONLY what is specified + object_mask = "mask[hostname,monitoringRobot[robotStatus]]" + for vsi in mgr.list_instances(mask=object_mask,hourly=True): + print vsi """ if 'mask' not in kwargs: @@ -147,18 +158,16 @@ def get_instance(self, instance_id, **kwargs): :returns: A dictionary containing a large amount of information about the specified instance. - :: + Example:: - # Print out the FQDN and IP address for instance ID 12345. - # env variables - # SL_USERNAME = YOUR_USERNAME - # SL_API_KEY = YOUR_API_KEY - import SoftLayer - client = SoftLayer.create_client_from_env() + # Print out instance ID 12345. + vsi = mgr.get_instance(12345) + print vsi - mgr = SoftLayer.VSManager(client) - vsi = mgr.get_instance(12345) - print vsi['fullyQualifiedDomainName'], vs['primaryIpAddress'] + # Print out only FQDN and primaryIP for instance 12345 + object_mask = "mask[fullyQualifiedDomainName,primaryIpAddress]" + vsi = mgr.get_instance(12345, mask=mask) + print vsi """ @@ -211,6 +220,11 @@ def get_create_options(self): :returns: A dictionary of creation options. + Example:: + + # Prints out the create option dictionary + options = mgr.get_create_options() + print(options) """ return self.guest.getCreateObjectOptions() @@ -219,17 +233,10 @@ def cancel_instance(self, instance_id): :param integer instance_id: the instance ID to cancel - :: + Example:: - # Cancel for instance ID 12345. - # env variables - # SL_USERNAME = YOUR_USERNAME - # SL_API_KEY = YOUR_API_KEY - import SoftLayer - client = SoftLayer.create_client_from_env() - - mgr = SoftLayer.VSManager(client) - mgr.cancel_instance(12345) + # Cancels instance 12345 + mgr.cancel_instance(12345) """ return self.guest.deleteObject(id=instance_id) @@ -242,17 +249,15 @@ def reload_instance(self, instance_id, post_uri=None, ssh_keys=None): after reload :param list ssh_keys: The SSH keys to add to the root user - :: + .. warning:: + Post-provision script MUST be HTTPS for it to be executed. + This will reformat the primary drive. - # Reload instance ID 12345 then run a custom post-provision script. - # env variables - # SL_USERNAME = YOUR_USERNAME - # SL_API_KEY = YOUR_API_KEY - import SoftLayer - client = SoftLayer.create_client_from_env() + Example:: + # Reload instance ID 12345 then run a custom post-provision script. + # Post-provision script MUST be HTTPS for it to be executed. post_uri = 'https://somehost.com/bootstrap.sh' - mgr = SoftLayer.VSManager(client) vsi = mgr.reload_instance(12345, post_uri=post_url) """ @@ -384,6 +389,11 @@ def wait_for_ready(self, instance_id, limit, delay=1, pending=False): Defaults to 1. :param bool pending: Wait for pending transactions not related to provisioning or reloads such as monitoring. + + Example:: + + # Will return once vsi 12345 is ready, or after 10 checks + ready = mgr.wait_for_ready(12345, 10) """ for count, new_instance in enumerate(itertools.repeat(instance_id), start=1): @@ -423,6 +433,28 @@ def verify_create_instance(self, **kwargs): Without actually placing an order. See :func:`create_instance` for a list of available options. + + Example:: + + new_vsi = { + 'domain': u'test01.labs.sftlyr.ws', + 'hostname': u'minion05', + 'datacenter': u'hkg02', + 'dedicated': False, + 'private': False, + 'cpus': 1, + 'os_code' : u'UBUNTU_LATEST', + 'hourly': True, + 'ssh_keys': [1234], + 'disks': ('100','25'), + 'local_disk': True, + 'memory': 1024 + } + + vsi = mgr.verify_create_instance(**new_vsi) + # vsi will be a SoftLayer_Container_Product_Order_Virtual_Guest + # if your order is correct. Otherwise you will get an exception + print vsi """ create_options = self._generate_create_dict(**kwargs) return self.guest.generateOrderTemplate(create_options) @@ -459,6 +491,30 @@ def create_instance(self, **kwargs): :param list ssh_keys: The SSH keys to add to the root user :param int nic_speed: The port speed to set :param string tags: tags to set on the VS as a comma separated list + + .. warning:: + This will add charges to your account + + Example:: + new_vsi = { + 'domain': u'test01.labs.sftlyr.ws', + 'hostname': u'minion05', + 'datacenter': u'hkg02', + 'dedicated': False, + 'private': False, + 'cpus': 1, + 'os_code' : u'UBUNTU_LATEST', + 'hourly': True, + 'ssh_keys': [1234], + 'disks': ('100','25'), + 'local_disk': True, + 'memory': 1024, + 'tags': 'test, pleaseCancel' + } + + vsi = mgr.create_instance(**new_vsi) + # vsi will have the newly created vsi details if done properly. + print vsi """ tags = kwargs.pop('tags', None) inst = self.guest.createObject(self._generate_create_dict(**kwargs)) @@ -471,6 +527,39 @@ def create_instances(self, config_list): This takes a list of dictionaries using the same arguments as create_instance(). + + .. warning:: + This will add charges to your account + + Example:: + # Define the instance we want to create. + new_vsi = { + 'domain': u'test01.labs.sftlyr.ws', + 'hostname': u'multi-test', + 'datacenter': u'hkg02', + 'dedicated': False, + 'private': False, + 'cpus': 1, + 'os_code' : u'UBUNTU_LATEST', + 'hourly': True, + 'ssh_keys': [87634], + 'disks': ('100','25'), + 'local_disk': True, + 'memory': 1024, + 'tags': 'test, pleaseCancel' + } + + # using .copy() so we can make changes to individual nodes + instances = [new_vsi.copy(), new_vsi.copy(), new_vsi.copy()] + + # give each its own hostname, not required. + instances[0]['hostname'] = "multi-test01" + instances[1]['hostname'] = "multi-test02" + instances[2]['hostname'] = "multi-test03" + + vsi = mgr.create_instances(config_list=instances) + #vsi will be a dictionary of all the new virtual servers + print vsi """ tags = [conf.pop('tags', None) for conf in config_list] @@ -491,6 +580,15 @@ def change_port_speed(self, instance_id, public, speed): True (default) means the public interface. False indicates the private interface. :param int speed: The port speed to set. + + .. warning:: + A port speed of 0 will disable the interface. + + Example:: + #change the Public interface to 10Mbps on instance 12345 + result = mgr.change_port_speed(instance_id=12345, + public=True, speed=10) + # result will be True or an Exception """ if public: func = self.guest.setPublicNetworkInterfaceSpeed @@ -535,7 +633,12 @@ def edit(self, instance_id, userdata=None, hostname=None, domain=None, :param string notes: notes about this particular VS :param string tags: tags to set on the VS as a comma separated list. Use the empty string to remove all tags. + :returns: bool -- True or an Exception + Example:: + # Change the hostname on instance 12345 to 'something' + result = mgr.edit(instance_id=12345 , hostname="something") + #result will be True or an Exception """ obj = {} @@ -563,6 +666,11 @@ def rescue(self, instance_id): """Reboot a VSI into the Xen recsue kernel. :param integer instance_id: the instance ID to rescue + :returns: bool -- True or an Exception + + Example:: + # Puts instance 12345 into rescue mode + result = mgr.rescue(instance_id=12345) """ return self.guest.executeRescueLayer(id=instance_id) @@ -577,6 +685,12 @@ def capture(self, instance_id, name, additional_disks=False, notes=None): attached storage devices :param string notes: notes about this particular image + :returns: dictionary -- information about the capture transaction. + + Example:: + name = "Testing Images" + notes = "Some notes about this image" + result = mgr.capture(instance_id=12345, name=name, notes=notes) """ vsi = self.get_instance(instance_id) @@ -602,12 +716,12 @@ def upgrade(self, instance_id, cpus=None, memory=None, :param int memory: RAM of the VS to be upgraded to. :param int nic_speed: The port speed to set - :: + :returns: bool + Example:: # Upgrade instance 12345 to 4 CPUs and 4 GB of memory import SoftLayer client = SoftLayer.create_client_from_env() - mgr = SoftLayer.VSManager(client) mgr.upgrade(12345, cpus=4, memory=4) diff --git a/SoftLayer/utils.py b/SoftLayer/utils.py index 622710f71..7a43ab483 100644 --- a/SoftLayer/utils.py +++ b/SoftLayer/utils.py @@ -180,7 +180,7 @@ def resolve_ids(identifier, resolvers): class UTC(datetime.tzinfo): - """UTC timezone""" + """UTC timezone.""" def utcoffset(self, _): return datetime.timedelta(0)