Add a query limit runtime modifier. (4.4.0)

The query_limit kwarg may now be used to add a cap to the number of
queries OGRe sends to public APIs.

Author: dmtucker

docs/conf.py

@@ -53,9 +53,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '4.3'
+version = '4.4'
 # The full version, including alpha/beta/rc tags.
-release = '4.3.0'
+release = '4.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/tutorial.rst

@@ -124,7 +124,7 @@ Alternatively, environment variables are checked when keys are unspecified.
    > --quantity 50 --location 37.781157 -122.398720 1 km
 
 .. seealso:: For a description of all available command line arguments, run:
-    
+
     .. code-block:: bash
 
        $ python -m ogre --help

ogre/Twitter.py

@@ -270,29 +270,36 @@ def twitter(
         log.setLevel(logging.INFO)
         log.info(qid+" Request: Twitter")
 
-    if not kinds or remaining < 1:
+    maximum_queries = kwargs.get("query_limit")
+    if maximum_queries is None:
+        maximum_queries = 450  # Twitter allows 450 queries every 15 minutes.
+
+    if not kinds or remaining < 1 or maximum_queries < 1:
         log.info(qid+" Success: No results were requested.")
         return []
 
     api = kwargs.get("api", Twython)(
         keychain["consumer_key"],
         access_token=keychain["access_token"]
     )
+
     limits = api.get_application_rate_limit_status()
-    maximum_queries = 450  # Twitter allows 450 queries every 15 minutes.
     try:
-        maximum_queries =\
-            int(limits["resources"]["search"]["/search/tweets"]["remaining"])
-        if maximum_queries < 1:
+        limit = int(
+            limits["resources"]["search"]["/search/tweets"]["remaining"]
+        )
+        if limit < 1:
             log.info(qid+" Failure: Queries are being limited.")
         else:
-            log.debug(qid+" Status: "+str(maximum_queries)+" queries remain.")
+            log.debug(qid+" Status: "+str(limit)+" queries remain.")
+        if limit < maximum_queries:
+            maximum_queries = limit
     except KeyError:
         log.warn(qid+" Unobtainable Rate Limit")
     total = remaining
 
     collection = []
-    for query in range(0, maximum_queries):
+    for query in range(maximum_queries):
         count = min(remaining, 100)  # Twitter accepts a max count of 100.
         try:
             results = api.search(

ogre/__init__.py

@@ -12,4 +12,4 @@
 
 from ogre.api import OGRe
 
-__version__ = "4.3.0"
+__version__ = "4.4.0"

ogre/__main__.py

@@ -78,6 +78,11 @@ def main():
         action="store_true",
         default=False
     )
+    parser.add_argument(
+        "--limit",
+        help="Specify a query limit.",
+        default=None
+    )
     parser.add_argument(
         "--strict",
         help="Ensure resulting media is specifically requested.",
@@ -104,6 +109,8 @@ def main():
     if args.interval is not None:
         args.interval[0] = float(args.interval[0])
         args.interval[1] = float(args.interval[1])
+    if args.limit is not None:
+        args.limit = int(args.limit)
 
     print json.dumps(
         OGRe(args.keys).fetch(
@@ -113,6 +120,7 @@ def main():
             quantity=args.quantity,
             location=args.location,
             interval=args.interval,
+            query_limit=args.limit,
             secure=args.insecure,
             strict_media=args.strict
         ),

ogre/test/test_Twitter.py

@@ -308,6 +308,31 @@ def test_twitter(self):
                 keyword="test",
                 quantity=0,
                 test=True,
+                test_message="Query Limit Fail-Fast",
+                api=self.api["regular"],
+                network=self.network["regular"]
+            ),
+            []
+        )
+        self.assertEqual(self.api["regular"].call_count, 0)
+        self.assertEqual(
+            self.api["regular"]().get_application_rate_limit_status.call_count,
+            0
+        )
+        self.assertEqual(self.api["regular"]().search.call_count, 0)
+        self.assertEqual(self.network["regular"].call_count, 0)
+
+        # Allowing < 1 query fails fast.
+        self.api["regular"].reset_mock()
+        self.network["regular"].reset_mock()
+        self.assertEqual(
+            twitter(
+                keys=self.retriever.keychain[
+                    self.retriever.keyring["twitter"]
+                ],
+                keyword="test",
+                query_limit=0,
+                test=True,
                 test_message="Quantity Fail-Fast",
                 api=self.api["regular"],
                 network=self.network["regular"]