Docs: Update Mobilize America (move-coop#394)

* Add Quickstart, improve Overview and Authentication Guide, minor edits to class

* reformat code to fix linting error which was created by adding underscore to '_request_paginate'

docs/mobilize_america.rst

@@ -5,15 +5,41 @@ Mobilize America
 Overview
 ********
 
-`Mobilize America <https://www.mobilizeamerica.io/>`_ is an activist signup tool used by progressive organizations. This class
-allows you to interact with the tool by leveraging their `API <https://github.com/mobilizeamerica/>`_ which is currently
-in alpha development.
+`Mobilize America <https://www.mobilizeamerica.io/>`_ is an activist signup tool used by progressive organizations.
+This class provides several methods for fetching organizations, people, and events from their
+`API <https://github.com/mobilizeamerica/api#mobilizeamerica-api>`_, which is currently in alpha development.
 
 .. note::
-   Public vs. Private Methods
-	Some of the methods require API keys to be furnished by Mobilize America while other end points are publicly
-	accessible and do not require authentication. Each method contains a note indicating whether it is public
-	or private.
+   Authentication
+    Some methods in the ``MobilizeAmerica`` class require an API Key furnished by Mobilize America (private methods),
+    while others do not (public methods). Each method in this class contains a note indicating whether it is public
+    or private. For more information, see the `API documentation <https://github.com/mobilizeamerica/api#authentication>`_.
+
+**********
+Quickstart
+**********
+
+If you instantiate ``MobilizeAmerica`` without an API Key, you can only use public methods:
+
+.. code-block:: python
+   from parsons import MobilizeAmerica
+
+   # Instantiate class without API key
+   ma = MobilizeAmerica()
+
+   # Use public method to get all organizations
+   ma.get_organizations()
+
+
+In order to use private methods, you must provide an API key either by setting the environmental
+variable ``MOBILIZE_AMERICA_API_KEY`` or by passing an ``api_key`` argument as shown below:
+
+.. code-block:: python
+   # Instantiate class without API key as argument
+   ma = MobilizeAmerica(api_key='my_api_key')
+
+   # Use private method to get all people
+   ma.get_people()
 
 ***
 API

parsons/mobilize_america/ma.py

@@ -31,9 +31,7 @@ def __init__(self, api_key=None):
             logger.info('Mobilize America API Key missing. Calling methods that rely on private'
                         ' endpoints will fail.')
 
-    def request(self, url, req_type='GET', post_data=None, args=None, auth=False):
-        # Internal request method
-
+    def _request(self, url, req_type='GET', post_data=None, args=None, auth=False):
         if auth:
 
             if not self.api_key:
@@ -51,16 +49,15 @@ def request(self, url, req_type='GET', post_data=None, args=None, auth=False):
 
         return r
 
-    def request_paginate(self, url, req_type='GET', post_data=None, args=None, raw=False,
-                         paginate=False, auth=False):
+    def _request_paginate(self, url, req_type='GET', args=None, auth=False):
 
-        r = self.request(url, req_type=req_type, args=args, auth=auth)
+        r = self._request(url, req_type=req_type, args=args, auth=auth)
 
         json = r.json()['data']
 
         while r.json()['next']:
 
-            r = self.request(r.json()['next'], req_type=req_type)
+            r = self._request(r.json()['next'], req_type=req_type)
             json.extend(r.json()['data'])
 
         return json
@@ -99,10 +96,10 @@ def get_organizations(self, updated_since=None):
                 See :ref:`parsons-table` for output options.
         """
 
-        return Table(self.request_paginate(self.uri + 'organizations',
-                                           args={
-                                               'updated_since': date_to_timestamp(updated_since)
-                                           }))
+        return Table(self._request_paginate(self.uri + 'organizations',
+                                            args={
+                                                'updated_since': date_to_timestamp(updated_since)
+                                            }))
 
     def get_events(self, organization_id=None, updated_since=None, timeslot_start=None,
                    timeslot_end=None, timeslots_table=False, max_timeslots=None):
@@ -149,7 +146,7 @@ def get_events(self, organization_id=None, updated_since=None, timeslot_start=No
                 'timeslot_start': self._time_parse(timeslot_start),
                 'timeslot_end': self._time_parse(timeslot_end)}
 
-        tbl = Table(self.request_paginate(self.uri + 'events', args=args))
+        tbl = Table(self._request_paginate(self.uri + 'events', args=args))
 
         if tbl.num_rows > 0:
 
@@ -243,7 +240,7 @@ def get_events_organization(self, organization_id=None, updated_since=None, time
                 'timeslot_end': self._time_parse(timeslot_end),
                 }
 
-        tbl = Table(self.request_paginate(self.uri + 'events', args=args, auth=True))
+        tbl = Table(self._request_paginate(self.uri + 'events', args=args, auth=True))
 
         if tbl.num_rows > 0:
 
@@ -286,7 +283,7 @@ def get_events_deleted(self, organization_id=None, updated_since=None):
         args = {'organization_id': organization_id,
                 'updated_since': date_to_timestamp(updated_since)}
 
-        return Table(self.request_paginate(self.uri + 'events/deleted', args=args))
+        return Table(self._request_paginate(self.uri + 'events/deleted', args=args))
 
     def get_people(self, organization_id=None, updated_since=None):
         """
@@ -306,10 +303,8 @@ def get_people(self, organization_id=None, updated_since=None):
         """
 
         url = self.uri + 'organizations/' + str(organization_id) + '/people'
-
-        return Table(self.request_paginate(url,
-                                           args={'updated_since': date_to_timestamp(updated_since)},
-                                           auth=True))
+        args = {'updated_since': date_to_timestamp(updated_since)}
+        return Table(self._request_paginate(url, args=args, auth=True))
 
     def get_attendances(self, organization_id=None, updated_since=None):
         """
@@ -330,7 +325,5 @@ def get_attendances(self, organization_id=None, updated_since=None):
         """
 
         url = self.uri + 'organizations/' + str(organization_id) + '/attendances'
-
-        return Table(self.request_paginate(url,
-                                           args={'updated_since': date_to_timestamp(updated_since)},
-                                           auth=True))
+        args = {'updated_since': date_to_timestamp(updated_since)}
+        return Table(self._request_paginate(url, args=args, auth=True))