Intellisense: doc comments and inbox (server) terminology

mailosaur/mailosaur_client.py

@@ -23,10 +23,38 @@
 
 
 class MailosaurClient(object):
-    """ Main class to access Mailosaur.com api. """
+    """The Mailosaur client - the main entry point to the Mailosaur API.
+
+    Construct an instance with your API key (or set the ``MAILOSAUR_API_KEY``
+    environment variable), then use the operations namespaces (``messages``,
+    ``servers``, ``files``, ``devices``, ``analysis``, ``previews``, ``usage``)
+    to automate email and SMS testing.
+
+    :ivar analysis: Operations for analyzing email content and deliverability, including spam scoring.
+    :vartype analysis: ~mailosaur.operations.analysis_operations.AnalysisOperations
+    :ivar files: Operations for downloading attachments, EML source, and email preview screenshots.
+    :vartype files: ~mailosaur.operations.files_operations.FilesOperations
+    :ivar messages: Operations for finding, retrieving, creating, and managing email and SMS messages.
+    :vartype messages: ~mailosaur.operations.messages_operations.MessagesOperations
+    :ivar servers: Operations for creating and managing your Mailosaur inboxes (servers).
+    :vartype servers: ~mailosaur.operations.servers_operations.ServersOperations
+    :ivar usage: Operations for inspecting account usage limits and recent transactional usage.
+    :vartype usage: ~mailosaur.operations.usage_operations.UsageOperations
+    :ivar devices: Operations for managing virtual security devices and retrieving their one-time passwords.
+    :vartype devices: ~mailosaur.operations.devices_operations.DevicesOperations
+    :ivar previews: Operations for discovering the email clients available for generating email previews.
+    :vartype previews: ~mailosaur.operations.previews_operations.PreviewsOperations
+    """
 
     def __init__(self, api_key=None, base_url="https://mailosaur.com/"):
-        """ Pass in your mailbox id and api key to authenticate """
+        """Returns an instance of the Mailosaur client.
+
+        :param api_key: Optional API key. Overrides the MAILOSAUR_API_KEY
+         environment variable if set.
+        :type api_key: str
+        :param base_url: Optionally overrides the base URL of the Mailosaur service.
+        :type base_url: str
+        """
         api_key = api_key or os.environ.get('MAILOSAUR_API_KEY')
 
         if not api_key:

mailosaur/models/message.py

@@ -34,7 +34,7 @@ class Message(object):
     :type attachments: list[~mailosaur.models.Attachment]
     :param metadata:
     :type metadata: ~mailosaur.models.Metadata
-    :param server: Identifier for the server in which the message is located.
+    :param server: Identifier for the inbox (server) in which the message is located.
     :type server: str
     """
 

mailosaur/models/server.py

@@ -1,15 +1,15 @@
 class Server(object):
-    """Server.
+    """A Mailosaur inbox (server) - a virtual SMTP/SMS endpoint.
 
-    :param id: Unique identifier for the server. Used as username for
+    :param id: Unique identifier for the inbox (server). Used as username for
      SMTP/POP3 authentication.
     :type id: str
-    :param name: A name used to identify the server.
+    :param name: A name used to identify the inbox (server).
     :type name: str
     :param users: Users (excluding administrators) who have access to the
-     server.
+     inbox (server) when access is restricted.
     :type users: list[str]
-    :param messages: The number of messages currently in the server.
+    :param messages: The number of messages currently in the inbox (server).
     :type messages: int
     """
 

mailosaur/models/server_create_options.py

@@ -1,7 +1,7 @@
 class ServerCreateOptions(object):
-    """ServerCreateOptions.
+    """Options used to create a new Mailosaur inbox (server).
 
-    :param name: A name used to identify the server.
+    :param name: A name used to identify the inbox (server).
     :type name: str
     """
 

mailosaur/models/server_list_result.py

@@ -1,9 +1,9 @@
 class ServerListResult(object):
-    """The result of a server listing request.
+    """The result of an inbox (server) listing request.
 
-    :param items: The individual servers forming the result. Servers are
-     returned sorted by creation date, with the most recently-created server
-     appearing first.
+    :param items: The individual inboxes (servers) forming the result. Inboxes
+     (servers) are returned sorted by creation date, with the most
+     recently-created inbox (server) appearing first.
     :type items: list[~mailosaur.models.Server]
     """
 

mailosaur/operations/analysis_operations.py

@@ -3,7 +3,9 @@
 from ..models import DeliverabilityReport
 
 class AnalysisOperations(object):
-    """AnalysisOperations operations.
+    """Operations for analyzing the content and deliverability of an email, including
+    SpamAssassin scoring and per-provider deliverability reports.
+    Accessed via ``client.analysis``.
     """
 
     def __init__(self, session, base_url, handle_http_error):
@@ -12,16 +14,12 @@ def __init__(self, session, base_url, handle_http_error):
         self.handle_http_error = handle_http_error
 
     def spam(self, email):
-        """Perform a spam test.
+        """Perform a spam analysis of an email.
 
-        Perform spam testing on the specified email.
-
-        :param email: The identifier of the email to be analyzed.
-        :type email: str        
-        :return: SpamAnalysisResult
+        :param email: The identifier of the message to be analyzed.
+        :type email: str
+        :return: A result containing the spam score and filter results.
         :rtype: ~mailosaur.models.SpamAnalysisResult
-        :raises:
-         :class:`MailosaurException<mailosaur.models.MailosaurException>`
         """
         url = "%sapi/analysis/spam/%s" % (self.base_url, email)
         response = self.session.get(url)
@@ -35,16 +33,12 @@ def spam(self, email):
         return SpamAnalysisResult(data)
 
     def deliverability(self, email):
-        """Perform a deliverability test.
-
-        Perform deliverability testing on the specified email.
+        """Perform a deliverability report of an email.
 
-        :param email: The identifier of the email to be analyzed.
-        :type email: str        
-        :return: DeliverabilityReport
+        :param email: The identifier of the message to be analyzed.
+        :type email: str
+        :return: A deliverability report for the email.
         :rtype: ~mailosaur.models.DeliverabilityReport
-        :raises:
-         :class:`MailosaurException<mailosaur.models.MailosaurException>`
         """
         url = "%sapi/analysis/deliverability/%s" % (self.base_url, email)
         response = self.session.get(url)

mailosaur/operations/devices_operations.py

@@ -10,7 +10,9 @@
 
 
 class DevicesOperations(object):
-    """DevicesOperations operations.
+    """Operations for managing virtual security devices and retrieving their current
+    one-time passwords (OTPs), used to automate testing of app-based multi-factor
+    authentication. Accessed via ``client.devices``.
     """
 
     def __init__(self, session, base_url, handle_http_error):
@@ -19,20 +21,24 @@ def __init__(self, session, base_url, handle_http_error):
         self.handle_http_error = handle_http_error
 
     def generate_email_address(self, server):
+        """Generates a random email address by appending a random string in front of
+        the domain name of the inbox (server).
+
+        :param server: The identifier of the inbox (server).
+        :type server: str
+        :return: A random email address ending in the domain of the inbox (server).
+        :rtype: str
+        """
         host = os.getenv('MAILOSAUR_SMTP_HOST', 'mailosaur.net')
         randomString = ''.join(random.choice(
             string.ascii_uppercase + string.digits) for _ in range(10))
         return "%s@%s.%s" % (randomString, server, host)
 
     def list(self):
-        """List all devices.
-
-        Returns a list of your virtual security devices.
+        """Returns a list of your virtual security devices.
 
-        :return: DeviceListResult
+        :return: A result containing your devices.
         :rtype: ~mailosaur.models.DeviceListResult
-        :raises:
-         :class:`MailosaurException<mailosaur.models.MailosaurException>`
         """
         url = "%sapi/devices" % (self.base_url)
         response = self.session.get(url)
@@ -46,16 +52,12 @@ def list(self):
         return DeviceListResult(data)
 
     def create(self, device_create_options):
-        """Create a device.
+        """Creates a new virtual security device.
 
-        Creates a new virtual security device and returns it.
-
-        :param device_create_options:
+        :param device_create_options: Options used to create a new Mailosaur virtual security device.
         :type device_create_options: ~mailosaur.models.DeviceCreateOptions
-        :return: Device
+        :return: The newly-created device.
         :rtype: ~mailosaur.models.Device
-        :raises:
-         :class:`MailosaurException<mailosaur.models.MailosaurException>`
         """
         url = "%sapi/devices" % (self.base_url)
         response = self.session.post(url, json=device_create_options.to_json())
@@ -69,17 +71,13 @@ def create(self, device_create_options):
         return Device(data)
 
     def otp(self, query):
-        """Retrieves the current one-time password for a saved device, or given base32-encoded shared secret.
-
-        Retrieves the detail for a single server. Simply supply the unique
-        identifier for the required server.
+        """Retrieves the current one-time password for a saved device, or given
+        base32-encoded shared secret.
 
         :param query: Either the unique identifier of the device, or a base32-encoded shared secret.
-        :type query: str        
-        :return: OtpResult
+        :type query: str
+        :return: A result containing the current one-time password.
         :rtype: ~mailosaur.models.OtpResult
-        :raises:
-         :class:`MailosaurException<mailosaur.models.MailosaurException>`
         """
         if "-" in query:
             url = "%sapi/devices/%s/otp" % (self.base_url, query)
@@ -106,16 +104,14 @@ def otp(self, query):
 
     def delete(
             self, id):
-        """Delete a device.
+        """Permanently delete a virtual security device.
 
-        Permanently delete a virtual security device. This operation cannot be undone.
+        This operation cannot be undone.
 
-        :param id: The identifier of the device to be deleted.
-        :type id: str        
+        :param id: The unique identifier of the device.
+        :type id: str
         :return: None
         :rtype: None
-        :raises:
-         :class:`MailosaurException<mailosaur.models.MailosaurException>`
         """
         url = "%sapi/devices/%s" % (self.base_url, id)
         response = self.session.delete(url)

mailosaur/operations/files_operations.py

@@ -4,7 +4,9 @@
 
 
 class FilesOperations(object):
-    """FilesOperations operations.
+    """Operations for downloading the raw content associated with a message - file
+    attachments, the full EML source of an email, and rendered email previews.
+    Accessed via ``client.files``.
     """
 
     def __init__(self, session, base_url, handle_http_error):
@@ -13,17 +15,12 @@ def __init__(self, session, base_url, handle_http_error):
         self.handle_http_error = handle_http_error
 
     def get_attachment(self, id):
-        """Download an attachment.
+        """Downloads a single attachment.
 
-        Downloads a single attachment. Simply supply the unique identifier for
-        the required attachment.
-
-        :param id: The identifier of the attachment to be downloaded.
+        :param id: The identifier for the required attachment.
         :type id: str
-        :return: object
-        :rtype: Generator
-        :raises:
-         :class:`HttpOperationError<msrest.exceptions.HttpOperationError>`
+        :return: A streamed response whose body contains the attachment's binary content.
+        :rtype: ~requests.Response
         """
         url = "%sapi/files/attachments/%s" % (self.base_url, id)
         response = self.session.get(url, stream=True)
@@ -35,17 +32,12 @@ def get_attachment(self, id):
         return response
 
     def get_email(self, id):
-        """Download EML.
-
-        Downloads an EML file representing the specified email. Simply supply
-        the unique identifier for the required email.
+        """Downloads an EML file representing the specified email.
 
-        :param id: The identifier of the email to be downloaded.
+        :param id: The identifier for the required message.
         :type id: str
-        :return: object
-        :rtype: Generator
-        :raises:
-         :class:`HttpOperationError<msrest.exceptions.HttpOperationError>`
+        :return: A streamed response whose body contains the raw EML content of the email.
+        :rtype: ~requests.Response
         """
         url = "%sapi/files/email/%s" % (self.base_url, id)
         response = self.session.get(url, stream=True)
@@ -57,17 +49,17 @@ def get_email(self, id):
         return response
 
     def get_preview(self, id):
-        """Download an email preview.
+        """Downloads a screenshot of your email rendered in a real email client.
 
-        Downloads a screenshot of your email rendered in a real email client. Simply supply
-        the unique identifier for the required preview.
+        Simply supply the unique identifier for the required preview.
 
         :param id: The identifier of the email preview to be downloaded.
         :type id: str
-        :return: object
-        :rtype: Generator
-        :raises:
-         :class:`HttpOperationError<msrest.exceptions.HttpOperationError>`
+        :return: A streamed response whose body contains the preview screenshot image.
+        :rtype: ~requests.Response
+        :raises: :class:`MailosaurException<mailosaur.models.MailosaurException>`
+         with error type ``preview_timeout`` if the preview is not generated
+         within the time limit.
         """
         timeout = 120000
         poll_count = 0