docstring updates and formatting

Author: Aaron Gonzales

searchtweets/api_utils.py

@@ -54,13 +54,15 @@
 def convert_utc_time(datetime_str):
     """
     Handles datetime argument conversion to the GNIP API format, which is
-    `YYYYMMDDHHSS`. Flexible passing of date formats.
+    `YYYYMMDDHHSS`. Flexible passing of date formats in the following types::
+
+        - YYYYmmDDHHMM
+        - YYYY-mm-DD
+        - YYYY-mm-DD HH:MM
+        - YYYY-mm-DDTHH:MM
 
     Args:
-        datetime_str (str): the datestring, which can either be in GNIP API
-        Format (YYYYmmDDHHSS), ISO date format (YYYY-mm-DD), ISO datetime
-        format (YYYY-mm-DD HH:mm),
-        or command-line ISO format (YYYY-mm-DDTHH:mm)
+        datetime_str (str): valid formats are listed above.
 
     Returns:
         string of GNIP API formatted date.

searchtweets/result_stream.py

@@ -3,9 +3,9 @@
 # Licensed under the MIT License
 # https://opensource.org/licenses/MIT
 """
-This module contains the request handing and actual api wrapping functionality.
+This module contains the request handing and actual API wrapping functionality.
 
-It's core method is the ``ResultStream`` object, which takes the API call
+Its core method is the ``ResultStream`` object, which takes the API call
 arguments and returns a stream of results to the user.
 """
 
@@ -30,7 +30,7 @@
 
 def make_session(username=None, password=None, bearer_token=None):
     """Creates a Requests Session for use. Accepts a bearer token
-    for freemium users and will override username and password information if
+    for premiums users and will override username and password information if
     present.
 
     Args:
@@ -113,7 +113,7 @@ def request(session, url, rule_payload, **kwargs):
     Args:
         session (requests.Session): the valid session object
         url (str): Valid API endpoint
-        rule_payload (str or dict): rule package for the POST. if you pass a
+        rule_payload (str or dict): rule package for the POST. If you pass a
             dictionary, it will be converted into JSON.
     """
     if isinstance(rule_payload, dict):
@@ -187,8 +187,8 @@ def __init__(self, endpoint, rule_payload, username=None, password=None,
     def stream(self):
         """
         Main entry point for the data from the API. Will automatically paginate
-        through the results via the 'next' token and return up to `max_results`
-        tweets or up to `max_requests` api calls, whichever is lower.
+        through the results via the ``next`` token and return up to ``max_results``
+        tweets or up to ``max_requests`` API calls, whichever is lower.
 
         Usage:
             >>> result_stream = ResultStream(**kwargs)
@@ -235,12 +235,12 @@ def check_counts(self):
         Disables tweet parsing if the count API is used.
         """
         if "counts" in re.split("[/.]", self.endpoint):
-            logger.info("disabling tweet parsing due to counts api usage")
+            logger.info("disabling tweet parsing due to counts API usage")
             self._tweet_func = lambda x: x
 
     def execute_request(self):
         """
-        Sends the request to the api and parses the json response.
+        Sends the request to the API and parses the json response.
         Makes some assumptions about the session length and sets the presence
         of a "next" token.
         """
@@ -268,15 +268,15 @@ def __repr__(self):
 
 def collect_results(rule, max_results=500, result_stream_args=None):
     """
-    Utility function to quickly get a list of tweets from a resultstream
-    without keeping the object around. Rqequires your args to be configured
+    Utility function to quickly get a list of tweets from a ``ResultStream``
+    without keeping the object around. Requires your args to be configured
     prior to using.
 
     Args:
         rule (str): valid powertrack rule for your account, preferably
         generated by the `gen_rule_payload` function.
         max_results (int): maximum number of tweets or counts to return from
-        the API / underlying resultstream object.
+        the API / underlying ``ResultStream`` object.
         result_stream_args (dict): configuration dict that has connection
         information for a ``ResultStream`` object.
 

searchtweets/utils.py

@@ -98,17 +98,17 @@ def write_ndjson(filename, data_iterable, append=False, **kwargs):
 def write_result_stream(result_stream, filename_prefix=None,
                         results_per_file=None, **kwargs):
     """
-    Wraps a resultstream object to save it to a file. This function will still
+    Wraps a ``ResultStream`` object to save it to a file. This function will still
     return all data from the result stream as a generator that wraps the
-    `write_ndjson` method.
+    ``write_ndjson`` method.
 
     Args:
         result_stream (ResultStream): the unstarted ResultStream object
         filename_prefix (str or None): the base name for file writing
         results_per_file (int or None): the maximum number of tweets to write
         per file. Defaults to having no max, which means one file. Multiple
         files will be named by datetime, according to
-        "<prefix>_YYY-mm-ddTHH_MM_SS.json".
+        ``<prefix>_YYY-mm-ddTHH_MM_SS.json``.
 
     """
     if isinstance(result_stream, types.GeneratorType):
@@ -141,9 +141,7 @@ def write_result_stream(result_stream, filename_prefix=None,
 def read_config(filename):
     """Reads and flattens a configuration file into a single
     dictionary for ease of use. Works with both ``.config`` and
-    ``.yaml`` files. Files should look like this:
-
-    .. code: yaml
+    ``.yaml`` files. Files should look like this::
 
         search_rules:
             from-date: 2017-06-01
@@ -159,9 +157,8 @@ def read_config(filename):
             filename_prefix: kanye
             results_per_file: 10000000
 
-    or
+    or::
 
-    .. parsed-literal:
 
         [search_rules]
         from_date = 2017-06-01

tools/search_tweets.py

@@ -96,15 +96,14 @@ def parse_cmd_args():
     argparser.add_argument("--max-results", dest="max_results",
                            default=500,
                            type=int,
-                           help="Maximum results to return for this "
-                                "session (defaults to 500; "
-                                "see -a option")
+                           help="Maximum number of Tweets or Counts to return for this "
+                                "session (defaults to 500)")
 
     argparser.add_argument("--max-pages",
                            dest="max_pages",
                            type=int,
                            default=None,
-                           help="Maximum number of pages/api calls to "
+                           help="Maximum number of pages/API calls to "
                            "use for this session.")
 
     argparser.add_argument("--results-per-file", dest="results_per_file",