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 @@
+"""Modules to help with common tasks."""

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
 
@@ -35,20 +35,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)