Adding some doc examples - Issues258

SoftLayer/managers/hardware.py

@@ -26,6 +26,15 @@ 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 +55,11 @@ 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 = mrg.cancel_hardware(hardware_id=1234)
+            print result
         """
         # Check to see if this is actually a pre-configured server (BMC). They
         # require a different cancellation call.
@@ -80,6 +94,10 @@ def cancel_metal(self, hardware_id, immediate=False):
         :param bool immediate: If true, the bare metal instance will be
                                cancelled immediately. Otherwise, it will be
                                scheduled to cancel on the anniversary date.
+        Example::
+
+            result = mgr.cancel_metal(hardware_id=1234)
+            print result
         """
         hw_billing = self.get_hardware(hardware_id,
                                        mask='mask[id, billingItem.id]')
@@ -112,6 +130,14 @@ 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)
+            print result
+
         """
         if 'mask' not in kwargs:
             hw_items = [
@@ -181,6 +207,12 @@ 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 = mrg.get_hardware(hardware_id=1234,mask=object_mask)
+            print result
         """
 
         if 'mask' not in kwargs:
@@ -248,6 +280,11 @@ 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)
+            print result
         """
         return self.hardware.bootToRescueLayer(id=hardware_id)
 
@@ -259,6 +296,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
+            print result
         """
         if public:
             func = self.hardware.setPublicNetworkInterfaceSpeed
@@ -288,6 +335,65 @@ def place_order(self, **kwargs):
         :param boolean no_public: True if this server should only have private
                                   interfaces
         :param list extras: List of extra feature names
+
+        .. warning::
+           Due to how the ordering structure currently works, all ordering
+           takes place using price IDs rather than quantities. See the
+           following sample for an example of using HardwareManager functions
+           for ordering a basic server.
+
+        Example::
+
+           # client is assumed to be an initialized SoftLayer.API.Client object
+           mgr = HardwareManager(client)
+
+           # Package ID 32 corresponds to the 'Quad Processor, Quad Core Intel'
+           # package. This information can be obtained from the
+           # :func:`get_available_dedicated_server_packages` function.
+           options = mgr.get_dedicated_server_create_options(32)
+
+           # Review the contents of options to find the information that
+           # applies to your order. For the sake of this example, we assume
+           # that your selections are a series of item IDs for each category
+           # organized into a key-value dictionary.
+
+           # This contains selections for all required categories
+           selections = {
+               'server': 542, # Quad Processor Quad Core Intel 7310 - 1.60GHz
+               'pri_ip_addresses': 15, # 1 IP Address
+               'notification': 51, # Email and Ticket
+               'ram': 280, # 16 GB FB-DIMM Registered 533/667
+               'bandwidth': 173, # 5000 GB Bandwidth
+               'lockbox': 45, # 1 GB Lockbox
+               'monitoring': 49, # Host Ping
+               'disk0': 14, # 500GB SATA II (for the first disk)
+               'response': 52, # Automated Notification
+               'port_speed': 187, # 100 Mbps Public & Private Networks
+               'power_supply': 469, # Redundant Power Supplies
+               'disk_controller': 487, # Non-RAID
+               'vulnerability_scanner': 307, # Nessus
+               'vpn_management': 309, # Unlimited SSL VPN Users
+               'remote_management': 504, # Reboot / KVM over IP
+               'os': 4166, # Ubuntu Linux 12.04 LTS Precise Pangolin (64 bit)
+           }
+
+           args = {
+               'location': 'FIRST_AVAILABLE', # Pick the first available DC
+               'packageId': 32, # From above
+               'disks': [],
+           }
+
+           for cat, item_id in selections:
+               for item in options['categories'][cat]['items'].items():
+                   if item['id'] == item_id:
+                       if 'disk' not in cat or 'disk_controller' == cat:
+                           args[cat] = item['price_id']
+                       else:
+                           args['disks'].append(item['price_id'])
+
+           # You can call :func:`verify_order` here to test the order instead
+           # of actually placing it if you prefer.
+           result = mgr.place_order(**args)
         """
         create_options = self._generate_create_dict(**kwargs)
         return self.client['Product_Order'].placeOrder(create_options)
@@ -503,6 +609,12 @@ 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
+            print result
+
         """
 
         obj = {}
@@ -539,6 +651,12 @@ 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)
+            print result
         """
 
         return self.hardware.createFirmwareUpdateTransaction(

SoftLayer/managers/ssl.py

@@ -11,6 +11,17 @@ 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 +35,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 +59,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 +72,12 @@ 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)
+            print result
+
         """
         return self.ssl.deleteObject(id=cert_id)
 
@@ -61,6 +89,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 +104,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)