code cleanup and docs

Author: allmightyspiff

SoftLayer/CLI/account/event_detail.py

@@ -32,6 +32,7 @@ def cli(env, identifier, ack):
 
 
 def basic_event_table(event):
+    """Formats a basic event table"""
     table = formatting.Table(["Id", "Status", "Type", "Start", "End"], title=event.get('subject'))
 
     table.add_row([
@@ -46,6 +47,7 @@ def basic_event_table(event):
 
 
 def impacted_table(event):
+    """Formats a basic impacted resources table"""
     table = formatting.Table([
         "Type", "Id", "hostname", "privateIp", "Label"
     ])
@@ -61,6 +63,7 @@ def impacted_table(event):
 
 
 def update_table(event):
+    """Formats a basic event update table"""
     update_number = 0
     for update in event.get('updates', []):
         header = "======= Update #%s on %s =======" % (update_number, utils.clean_time(update.get('startDate')))

SoftLayer/CLI/account/events.py

@@ -1,11 +1,9 @@
 """Summary and acknowledgement of upcoming and ongoing maintenance events"""
 # :license: MIT, see LICENSE for more details.
-from pprint import pprint as pp
 import click
 
 import SoftLayer
 from SoftLayer.CLI import environment
-from SoftLayer.CLI import exceptions
 from SoftLayer.CLI import formatting
 from SoftLayer.managers.account import AccountManager as AccountManager
 from SoftLayer import utils
@@ -18,7 +16,6 @@
 def cli(env, ack_all):
     """Summary and acknowledgement of upcoming and ongoing maintenance events"""
 
-    # Print a list of all on going maintenance
     manager = AccountManager(env.client)
     events = manager.get_upcoming_events()
 
@@ -27,9 +24,6 @@ def cli(env, ack_all):
             result = manager.ack_event(event['id'])
             event['acknowledgedFlag'] = result
     env.fout(event_table(events))
-    # pp(events)
-
-    # Allow ack all, or ack specific maintenance
 
 
 def event_table(events):

SoftLayer/CLI/account/invoice_detail.py

@@ -5,11 +5,9 @@
 
 import SoftLayer
 from SoftLayer.CLI import environment
-from SoftLayer.CLI import exceptions
 from SoftLayer.CLI import formatting
 from SoftLayer.managers.account import AccountManager as AccountManager
 from SoftLayer import utils
-from pprint import pprint as pp
 
 
 @click.command()
@@ -60,4 +58,5 @@ def cli(env, identifier, details):
 
 
 def nice_string(ugly_string, limit=100):
+    """Format and trims strings"""
     return (ugly_string[:limit] + '..') if len(ugly_string) > limit else ugly_string

SoftLayer/CLI/account/invoices.py

@@ -21,8 +21,6 @@
 def cli(env, limit, closed=False, get_all=False):
     """Invoices and all that mess"""
 
-    # List invoices
-
     manager = AccountManager(env.client)
     invoices = manager.get_invoices(limit, closed, get_all)
 

SoftLayer/managers/account.py

@@ -27,6 +27,10 @@ def __init__(self, client):
         self.client = client
 
     def get_summary(self):
+        """Gets some basic account information
+
+        :return: Account object
+        """
         mask = """mask[
             nextInvoiceTotalAmount,
             pendingInvoice[invoiceTotalAmount],
@@ -45,6 +49,10 @@ def get_summary(self):
         return self.client.call('Account', 'getObject', mask=mask)
 
     def get_upcoming_events(self):
+        """Retreives a list of Notification_Occurrence_Events that have not ended yet
+
+        :return: SoftLayer_Notification_Occurrence_Event
+        """
         mask = "mask[id, subject, startDate, endDate, statusCode, acknowledgedFlag, impactedResourceCount, updateCount]"
         _filter = {
             'endDate': {
@@ -61,9 +69,19 @@ def get_upcoming_events(self):
         return self.client.call('Notification_Occurrence_Event', 'getAllObjects', filter=_filter, mask=mask, iter=True)
 
     def ack_event(self, event_id):
+        """Acknowledge an event. This mostly prevents it from appearing as a notification in the control portal.
+
+        :param int event_id: Notification_Occurrence_Event ID you want to ack
+        :return: True on success, Exception otherwise.
+        """
         return self.client.call('Notification_Occurrence_Event', 'acknowledgeNotification', id=event_id)
 
     def get_event(self, event_id):
+        """Gets details about a maintenance event
+
+        :param int event_id: Notification_Occurrence_Event ID
+        :return: Notification_Occurrence_Event  
+        """
         mask = """mask[
             acknowledgedFlag,
             attachments,
@@ -75,6 +93,13 @@ def get_event(self, event_id):
         return self.client.call('Notification_Occurrence_Event', 'getObject', id=event_id, mask=mask)
 
     def get_invoices(self, limit=50, closed=False, get_all=False):
+        """Gets an accounts invoices.
+
+        :param int limit: Number of invoices to get back in a single call.
+        :param bool closed: If True, will also get CLOSED invoices
+        :param bool get_all: If True, will paginate through invoices until all have been retrieved.
+        :return: Billing_Invoice
+        """
         mask = "mask[invoiceTotalAmount, itemCount]"
         _filter = {
             'invoices': {
@@ -94,6 +119,11 @@ def get_invoices(self, limit=50, closed=False, get_all=False):
         return self.client.call('Account', 'getInvoices', mask=mask, filter=_filter, iter=get_all, limit=limit)
 
     def get_billing_items(self, identifier):
+        """Gets all topLevelBillingItems from a specific invoice
+        
+        :param int identifier: Invoice Id
+        :return: Billing_Invoice_Item
+        """
 
         mask = """mask[
             id, description, hostName, domainName, oneTimeAfterTaxAmount, recurringAfterTaxAmount, createDate,

SoftLayer/utils.py

@@ -291,6 +291,11 @@ def clean_string(string):
 
 
 def clean_time(sltime, in_format='%Y-%m-%dT%H:%M:%S%z', out_format='%Y-%m-%d %H:%M'):
+    """Easy way to format time strings
 
+    :param string sltime: A softlayer formatted time string
+    :param string in_format: Datetime format for strptime
+    :param string out_format: Datetime format for strftime
+    """
     clean = datetime.datetime.strptime(sltime, in_format)
     return clean.strftime(out_format)

docs/api/managers/account.rst

@@ -0,0 +1,5 @@
+.. _account:
+
+.. automodule:: SoftLayer.managers.account
+   :members:
+   :inherited-members:

docs/cli/account.rst

@@ -0,0 +1,23 @@
+.. _cli_account:
+
+Account Commands
+
+.. click:: SoftLayer.cli.account.summary:cli
+    :prog: account summary
+    :show-nested:
+
+.. click:: SoftLayer.cli.account.events:cli
+    :prog: account events
+    :show-nested:
+
+.. click:: SoftLayer.cli.account.event-detail:cli
+    :prog: account event-detail
+    :show-nested:
+
+.. click:: SoftLayer.cli.account.invoices:cli
+    :prog: account invoices
+    :show-nested:
+
+.. click:: SoftLayer.cli.account.invoice-detail:cli
+    :prog: account invoice-detail
+    :show-nested: