rename pan.xapi log() sleep argument to interval and rework query

interval processing slightly.

add --timeout and --interval options for use with --log to panxapi.

Author: kevinsteves

bin/panxapi.py

@@ -157,8 +157,8 @@ def main():
                      nlogs=options['nlogs'],
                      skip=options['skip'],
                      filter=options['filter'],
-#                     sleep=None,
-                     timeout=None)
+                     interval=options['interval'],
+                     timeout=options['job_timeout'])
             print_status(xapi, action)
             print_response(xapi, options)
 
@@ -260,6 +260,8 @@ def parse_opts():
         'nlogs': None,
         'skip': None,
         'filter': None,
+        'interval': None,
+        'job_timeout': None,
         'api_key': None,
         'cafile': None,
         'capath': None,
@@ -289,6 +291,7 @@ def parse_opts():
                     'clone', 'export=', 'log=', 'recursive',
                     'cafile=', 'capath=', 'ls', 'serial=',
                     'group=', 'merge', 'nlogs=', 'skip=', 'filter=',
+                    'interval=', 'timeout=',
                     ]
 
     try:
@@ -378,6 +381,10 @@ def parse_opts():
             options['skip'] = arg
         elif opt == '--filter':
             options['filter'] = arg
+        elif opt == '--interval':
+            options['interval'] = arg
+        elif opt == '--timeout':
+            options['job_timeout'] = arg
         elif opt == '-h':
             options['hostname'] = arg
         elif opt == '-K':
@@ -656,6 +663,8 @@ def usage():
     --nlogs num           retrieve num logs
     --skip num            skip num logs
     --filter filter       log selection filter
+    --interval            log job query interval
+    --timeout             log job query timeout
     -K api_key
     -x                    print XML response to stdout
     -p                    print XML response in Python to stdout

doc/pan.xapi.rst

@@ -329,7 +329,7 @@ export(category=None, from_name=None)
  **from_name** argument is used to specify the source for a file list
  or file export.
 
-log(self, log_type=None, nlogs=None, skip=None, filter=None, sleep=_job_sleep, timeout=None)
+log(self, log_type=None, nlogs=None, skip=None, filter=None, interval=None, timeout=None)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  The log() method performs the ``type=log`` retrieve log API request
@@ -360,7 +360,7 @@ log(self, log_type=None, nlogs=None, skip=None, filter=None, sleep=_job_sleep, t
 
  - **skip**
 
-  Specify the number of logs to skip. This can be used to retieve log
+  Specify the number of logs to skip. This can be used to retrieve log
   entries in batches by skipping previously retrieved logs.
 
   The default is 0.
@@ -378,12 +378,12 @@ log(self, log_type=None, nlogs=None, skip=None, filter=None, sleep=_job_sleep, t
  job ID returned in the initial request is complete and receive the log
  data.  Additional arguments to control the polling include:
 
- - **sleep**
+ - **interval**
 
-  A floating point number specifying the number of seconds to sleep
-  between each non-finished job status request.
+  A floating point number specifying the query interval in seconds
+  between each non-finished job status response.
 
-  The default is 0.5.
+  The default is 0.5 seconds.
 
  - **timeout**
 

lib/pan/xapi.py

@@ -44,7 +44,7 @@
 import pan.rc
 
 _encoding = 'utf-8'
-_job_sleep = 0.5
+_job_query_interval = 0.5
 
 
 class PanXapiError(Exception):
@@ -770,17 +770,19 @@ def export(self, category=None, from_name=None, to_name=None):
             self.export_result['category'] = category
 
     def log(self, log_type=None, nlogs=None, skip=None, filter=None,
-            sleep=_job_sleep, timeout=None):
+            interval=None, timeout=None):
         self.__set_api_key()
         self.__clear_response()
 
-        if sleep is not None:
-            try:
-                sleep = float(sleep)
-                if sleep < 0:
-                    raise ValueError
-            except ValueError:
-                raise PanXapiError('Invalid sleep: %s' % sleep)
+        if interval is None:
+            interval = _job_query_interval
+
+        try:
+            interval = float(interval)
+            if interval < 0:
+                raise ValueError
+        except ValueError:
+            raise PanXapiError('Invalid interval: %s' % interval)
 
         if timeout is not None:
             try:
@@ -811,7 +813,7 @@ def log(self, log_type=None, nlogs=None, skip=None, filter=None,
 
         job = self.element_root.find('./result/job')
         if job is None:
-            raise PanXapiError('no job element in type=log request')
+            raise PanXapiError('no job element in type=log response')
 
         query = {}
         query['type'] = 'log'
@@ -834,7 +836,7 @@ def log(self, log_type=None, nlogs=None, skip=None, filter=None,
             status = self.element_root.find('./result/job/status')
             if status is None:
                 raise PanXapiError('no status element in ' +
-                                   'type=log&action=get request')
+                                   'type=log&action=get response')
             if status.text == 'FIN':
                 return
 
@@ -847,10 +849,9 @@ def log(self, log_type=None, nlogs=None, skip=None, filter=None,
                 raise PanXapiError('timeout waiting for ' +
                                    'job %s completion' % job.text)
 
-            if sleep is not None:
-                if self.debug2:
-                    print('sleep %.2f seconds' % sleep, file=sys.stderr)
-                time.sleep(sleep)
+            if self.debug2:
+                print('sleep %.2f seconds' % interval, file=sys.stderr)
+            time.sleep(interval)
 
 if __name__ == '__main__':
     # python -m pan.xapi [tag] [xpath] [0-3]