Merge pull request #438 from gabrielkrell/pydoc-update

Update docstrings/pydoc/help (#170)

sendgrid/__init__.py

@@ -1,3 +1,20 @@
+"""
+This library allows you to quickly and easily use the SendGrid Web API v3 via
+Python.
+
+For more information on this library, see the README on Github.
+    https://github.com/sendgrid/sendgrid-python
+For more information on the SendGrid v3 API, see the v3 docs:
+    http://sendgrid.com/docs/API_Reference/api_v3.html
+For the user guide, code examples, and more, visit the main docs page:
+    http://sendgrid.com/docs/index.html
+
+Available subpackages
+---------------------
+helpers
+    Modules to help with common tasks.
+"""
+
 from .version import __version__  # noqa
 # v3 API
 from .sendgrid import SendGridAPIClient  # noqa

sendgrid/helpers/__init__.py

@@ -0,0 +1,19 @@
+"""v3/mail/send response body builder
+
+Builder for assembling emails to be sent with the v3 SendGrid API.
+
+Usage example:
+    def build_hello_email():
+        to_email = from_email = Email("[email protected]")
+        subject = "Hello World from the SendGrid Python Library"
+        content = Content("text/plain", "some text here")
+        mail = Mail(from_email, subject, to_email, content)
+        mail.personalizations[0].add_to(Email("[email protected]"))
+        return mail.get()  # assembled request body
+
+For more usage examples, see
+https://github.com/sendgrid/sendgrid-python/tree/master/examples/helpers/mail
+
+For more information on the v3 API, see
+https://sendgrid.com/docs/API_Reference/api_v3.html
+"""

sendgrid/helpers/inbound/__init__.py

@@ -1,2 +1,13 @@
+"""
+Inbound Parse helper
+--------------------
+This is a standalone module to help get you started consuming and processing
+Inbound Parse data.  It provides a Flask server to listen for Inbound Parse
+POSTS, and utilities to send sample data to the server.
+
+See README.txt for detailed usage instructions, including quick-start guides
+for local testing and Heroku deployment.
+"""
+
 from .config import *  # noqa
 from .parse import *  # noqa

sendgrid/helpers/inbound/app.py

@@ -1,4 +1,6 @@
-"""Receiver module for processing SendGrid Inbound Parse messages"""
+"""Receiver module for processing SendGrid Inbound Parse messages.
+
+See README.txt for usage instructions."""
 try:
     from config import Config
 except:
@@ -20,11 +22,13 @@
 
 @app.route('/', methods=['GET'])
 def index():
+    """Show index page to confirm that server is running."""
     return render_template('index.html')
 
 
 @app.route(config.endpoint, methods=['POST'])
 def inbound_parse():
+    """Process POST from Inbound Parse and print received data."""
     parse = Parse(config, request)
     # Sample proccessing action
     print(parse.key_values())

sendgrid/helpers/inbound/config.py

@@ -1,4 +1,4 @@
-"""Setup credentials (.env) and application variables (config.yml)"""
+"""Set up credentials (.env) and application variables (config.yml)"""
 import os
 import yaml
 
@@ -39,20 +39,27 @@ def init_environment():
 
     @property
     def debug_mode(self):
+        """Flask debug mode - set to False in production."""
         return self._debug_mode
 
     @property
     def endpoint(self):
+        """Endpoint to receive Inbound Parse POSTs."""
         return self._endpoint
 
     @property
     def host(self):
+        """URL that the sender will POST to."""
         return self._host
 
     @property
     def keys(self):
+        """Incoming Parse fields to parse. For reference, see
+        https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html
+        """
         return self._keys
 
     @property
     def port(self):
+        """Port to listen on."""
         return self._port

sendgrid/helpers/inbound/send.py

@@ -1,4 +1,4 @@
-"""A module for sending test SendGrid Inbound Parse messages
+"""A module for sending test SendGrid Inbound Parse messages.
 Usage: ./send.py [path to file containing test data]"""
 import argparse
 import sys
@@ -12,9 +12,15 @@
 
 class Send(object):
     def __init__(self, url):
+        """Create a Send object with target `url`."""
         self._url = url
 
     def test_payload(self, payload_filepath):
+        """Send a test payload.
+
+        Load a payload from payload_filepath, apply headers, and POST self.url.
+        Return the response object.
+        """
         headers = {
             "User-Agent": "SendGrid-Test",
             "Content-Type": "multipart/form-data; boundary=xYzZY"
@@ -26,20 +32,23 @@ def test_payload(self, payload_filepath):
 
     @property
     def url(self):
+        """URL to send to."""
         return self._url
 
-config = Config()
-parser = argparse.ArgumentParser(description='Test data and optional host.')
-parser.add_argument('data',
-                    type=str,
-                    help='path to the sample data')
-parser.add_argument('-host',
-                    type=str,
-                    help='name of host to send the sample data to',
-                    default=config.host, required=False)
-args = parser.parse_args()
-send = Send(args.host)
-response = send.test_payload(sys.argv[1])
-print(response.status_code)
-print(response.headers)
-print(response.body)
+
+if __name__ == '__main__':
+    config = Config()
+    parser = argparse.ArgumentParser(description='Test data and optional host.')
+    parser.add_argument('data',
+                        type=str,
+                        help='path to the sample data')
+    parser.add_argument('-host',
+                        type=str,
+                        help='name of host to send the sample data to',
+                        default=config.host, required=False)
+    args = parser.parse_args()
+    send = Send(args.host)
+    response = send.test_payload(sys.argv[1])
+    print(response.status_code)
+    print(response.headers)
+    print(response.body)

sendgrid/helpers/mail/asm.py

@@ -1,6 +1,14 @@
 class ASM(object):
+    """An object specifying unsubscribe behavior."""
 
     def __init__(self, group_id=None, groups_to_display=None):
+        """Create an ASM with the given group_id and groups_to_display.
+
+        :param group_id: ID of an unsubscribe group
+        :type group_id: int, optional
+        :param groups_to_display: Unsubscribe groups to display
+        :type groups_to_display: list(int), optional
+        """
         self._group_id = None
         self._groups_to_display = None
 
@@ -12,6 +20,10 @@ def __init__(self, group_id=None, groups_to_display=None):
 
     @property
     def group_id(self):
+        """The unsubscribe group to associate with this email.
+
+        :rtype: integer
+        """
         return self._group_id
 
     @group_id.setter
@@ -20,13 +32,24 @@ def group_id(self, value):
 
     @property
     def groups_to_display(self):
+        """The unsubscribe groups that you would like to be displayed on the
+        unsubscribe preferences page. Max of 25 groups.
+
+        :rtype: list(int)
+        """
         return self._groups_to_display
 
     @groups_to_display.setter
     def groups_to_display(self, value):
         self._groups_to_display = value
 
     def get(self):
+        """
+        Get a JSON-ready representation of this ASM.
+
+        :returns: This ASM, ready for use in a request body.
+        :rtype: dict
+        """
         asm = {}
         if self.group_id is not None:
             asm["group_id"] = self.group_id

sendgrid/helpers/mail/attachment.py

@@ -1,6 +1,8 @@
 class Attachment(object):
+    """An attachment to be included with an email."""
 
     def __init__(self):
+        """Create an empty Attachment."""
         self._content = None
         self._type = None
         self._filename = None
@@ -9,6 +11,10 @@ def __init__(self):
 
     @property
     def content(self):
+        """The Base64 encoded content of the attachment.
+
+        :rtype: string
+        """
         return self._content
 
     @content.setter
@@ -17,6 +23,10 @@ def content(self, value):
 
     @property
     def type(self):
+        """The MIME type of the content you are attaching.
+
+        :rtype: string
+        """
         return self._type
 
     @type.setter
@@ -25,6 +35,10 @@ def type(self, value):
 
     @property
     def filename(self):
+        """The filename of the attachment.
+
+        :rtype: string
+        """
         return self._filename
 
     @filename.setter
@@ -33,6 +47,17 @@ def filename(self, value):
 
     @property
     def disposition(self):
+        """The content-disposition of the attachment, specifying display style.
+
+        Specifies how you would like the attachment to be displayed.
+         - "inline" results in the attached file being displayed automatically
+            within the message.
+         - "attachment" results in the attached file requiring some action to
+            display (e.g. opening or downloading the file).
+        If unspecified, "attachment" is used. Must be one of the two choices.
+
+        :rtype: string
+        """
         return self._disposition
 
     @disposition.setter
@@ -41,13 +66,26 @@ def disposition(self, value):
 
     @property
     def content_id(self):
+        """The content id for the attachment.
+
+        This is used when the disposition is set to "inline" and the attachment
+        is an image, allowing the file to be displayed within the email body.
+
+        :rtype: string
+        """
         return self._content_id
 
     @content_id.setter
     def content_id(self, value):
         self._content_id = value
 
     def get(self):
+        """
+        Get a JSON-ready representation of this Attachment.
+
+        :returns: This Attachment, ready for use in a request body.
+        :rtype: dict
+        """
         attachment = {}
         if self.content is not None:
             attachment["content"] = self.content

sendgrid/helpers/mail/bcc_settings.py

@@ -1,6 +1,18 @@
 class BCCSettings(object):
+    """Settings object for automatic BCC.
+
+    This allows you to have a blind carbon copy automatically sent to the
+    specified email address for every email that is sent.
+    """
 
     def __init__(self, enable=None, email=None):
+        """Create a BCCSettings.
+
+        :param enable: Whether this BCCSettings is applied to sent emails.
+        :type enable: boolean, optional
+        :param email: Who should be BCCed.
+        :type email: Email, optional
+        """
         self._enable = None
         self._email = None
 
@@ -12,6 +24,10 @@ def __init__(self, enable=None, email=None):
 
     @property
     def enable(self):
+        """Indicates if this setting is enabled.
+
+        :rtype: boolean
+        """
         return self._enable
 
     @enable.setter
@@ -20,13 +36,23 @@ def enable(self, value):
 
     @property
     def email(self):
+        """The email address that you would like to receive the BCC.
+
+        :rtype: Email
+        """
         return self._email
 
     @email.setter
     def email(self, value):
         self._email = value
 
     def get(self):
+        """
+        Get a JSON-ready representation of this BCCSettings.
+
+        :returns: This BCCSettings, ready for use in a request body.
+        :rtype: dict
+        """
         bcc_settings = {}
         if self.enable is not None:
             bcc_settings["enable"] = self.enable