added updated cache time to apt, also started documenting return values

packaging/os/apt.py

@@ -138,6 +138,28 @@ EXAMPLES = '''
 - apt: pkg=foo state=build-dep
 '''
 
+RETURN = '''
+cache_updated:
+    description: if the cache was updated or not
+    returned: success, in some cases
+    type: boolean
+    sample: True
+cache_update_time:
+    description: time of the last cache update (0 if unknown)
+    returned: success, in some cases
+    type: datetime
+    sample: 1425828348000
+stdout:
+    description: output from apt
+    returned: success, when needed
+    type: string
+    sample: "Reading package lists...\nBuilding dependency tree...\nReading state information...\nThe following extra packages will be installed:\n  apache2-bin ..."
+stderr:
+    description: error output from apt
+    returned: success, when needed
+    type: string
+    sample: "AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1. Set the 'ServerName' directive globally to ..."
+'''
 
 import traceback
 # added to stave off future warnings about apt api
@@ -536,6 +558,8 @@ def main():
     if not APTITUDE_CMD and p.get('upgrade', None) in [ 'full', 'safe', 'yes' ]:
         module.fail_json(msg="Could not find aptitude. Please ensure it is installed.")
 
+    updated_cache = False
+    updated_cache_time = 0
     install_recommends = p['install_recommends']
     dpkg_options = expand_dpkg_options(p['dpkg_options'])
 
@@ -558,41 +582,41 @@ def main():
         if p['update_cache']:
             # Default is: always update the cache
             cache_valid = False
-            if p['cache_valid_time']:
-                tdelta = datetime.timedelta(seconds=p['cache_valid_time'])
+            now = datetime.datetime.now()
+            if p.get('cache_valid_time', False):
                 try:
                     mtime = os.stat(APT_UPDATE_SUCCESS_STAMP_PATH).st_mtime
                 except:
-                    mtime = False
-                if mtime is False:
                     # Looks like the update-success-stamp is not available
                     # Fallback: Checking the mtime of the lists
                     try:
                         mtime = os.stat(APT_LISTS_PATH).st_mtime
                     except:
+                        # No mtime could be read. We update the cache to be safe
                         mtime = False
-                if mtime is False:
-                    # No mtime could be read - looks like lists are not there
-                    # We update the cache to be safe
-                    cache_valid = False
-                else:
+
+                if mtime:
+                    tdelta = datetime.timedelta(seconds=p['cache_valid_time'])
                     mtimestamp = datetime.datetime.fromtimestamp(mtime)
-                    if mtimestamp + tdelta >= datetime.datetime.now():
-                        # dont update the cache
-                        # the old cache is less than cache_valid_time seconds old - so still valid
+                    if mtimestamp + tdelta >= now:
                         cache_valid = True
+                        updated_cache_time = int(time.mktime(mtimestamp.timetuple()))
 
             if cache_valid is not True:
                 cache.update()
                 cache.open(progress=None)
+                updated_cache = True
+                updated_cache_time = int(time.mktime(now.timetuple()))
             if not p['package'] and not p['upgrade'] and not p['deb']:
-                module.exit_json(changed=False)
+                module.exit_json(changed=False, cache_updated=updated_cache, cache_update_time=updated_cache_time)
+        else:
+            updated_cache = False
+            updated_cache_time = 0
 
         force_yes = p['force']
 
         if p['upgrade']:
-            upgrade(module, p['upgrade'], force_yes,
-                    p['default_release'], dpkg_options)
+            upgrade(module, p['upgrade'], force_yes, p['default_release'], dpkg_options)
 
         if p['deb']:
             if p['state'] != 'present':
@@ -622,6 +646,8 @@ def main():
                     force=force_yes, dpkg_options=dpkg_options,
                     build_dep=state_builddep)
             (success, retvals) = result
+            retvals['cache_updated']=updated_cache
+            retvals['cache_update_time']=updated_cache_time
             if success:
                 module.exit_json(**retvals)
             else: