Refactored configuration + cache support added

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,8 @@
 ## Description:
 **Related issue (if applicable):** fixes #<!--apprise issue number goes here-->
 
+<!-- Have anything else to describe? Define it here -->
+
 ## New Service Completion Status
 <!-- This section is only applicable if you're adding a new service -->
 * [ ] apprise/plugins/Notify<!--ServiceName goes here-->.py

apprise/AppriseConfig.py

@@ -56,8 +56,19 @@ def __init__(self, paths=None, asset=None, cache=True, **kwargs):
 
         If no path is specified then a default list is used.
 
-        If cache is set to True, then after the data is loaded, it's cached
-        within this object so it isn't retrieved again later.
+        By default we cache our responses so that subsiquent calls does not
+        cause the content to be retrieved again. Setting this to False does
+        mean more then one call can be made to retrieve the (same) data.  This
+        method can be somewhat inefficient if disabled and you're set up to
+        make remote calls.  Only disable caching if you understand the
+        consequences.
+
+        You can alternatively set the cache value to an int identifying the
+        number of seconds the previously retrieved can exist for before it
+        should be considered expired.
+
+        It's also worth nothing that the cache value is only set to elements
+        that are not already of subclass ConfigBase()
         """
 
         # Initialize a server list of URLs
@@ -67,24 +78,43 @@ def __init__(self, paths=None, asset=None, cache=True, **kwargs):
         self.asset = \
             asset if isinstance(asset, AppriseAsset) else AppriseAsset()
 
+        # Set our cache flag
+        self.cache = cache
+
         if paths is not None:
             # Store our path(s)
             self.add(paths)
 
         return
 
-    def add(self, configs, asset=None, tag=None):
+    def add(self, configs, asset=None, tag=None, cache=True):
         """
         Adds one or more config URLs into our list.
 
         You can override the global asset if you wish by including it with the
         config(s) that you add.
 
+        By default we cache our responses so that subsiquent calls does not
+        cause the content to be retrieved again. Setting this to False does
+        mean more then one call can be made to retrieve the (same) data.  This
+        method can be somewhat inefficient if disabled and you're set up to
+        make remote calls.  Only disable caching if you understand the
+        consequences.
+
+        You can alternatively set the cache value to an int identifying the
+        number of seconds the previously retrieved can exist for before it
+        should be considered expired.
+
+        It's also worth nothing that the cache value is only set to elements
+        that are not already of subclass ConfigBase()
         """
 
         # Initialize our return status
         return_status = True
 
+        # Initialize our default cache value
+        cache = cache if cache is not None else self.cache
+
         if isinstance(asset, AppriseAsset):
             # prepare default asset
             asset = self.asset
@@ -104,7 +134,7 @@ def add(self, configs, asset=None, tag=None):
                 'specified.'.format(type(configs)))
             return False
 
-        # Iterate over our
+        # Iterate over our configuration
         for _config in configs:
 
             if isinstance(_config, ConfigBase):
@@ -123,7 +153,8 @@ def add(self, configs, asset=None, tag=None):
 
             # Instantiate ourselves an object, this function throws or
             # returns None if it fails
-            instance = AppriseConfig.instantiate(_config, asset=asset, tag=tag)
+            instance = AppriseConfig.instantiate(
+                _config, asset=asset, tag=tag, cache=cache)
             if not isinstance(instance, ConfigBase):
                 return_status = False
                 continue
@@ -134,7 +165,7 @@ def add(self, configs, asset=None, tag=None):
         # Return our status
         return return_status
 
-    def servers(self, tag=MATCH_ALL_TAG, cache=True):
+    def servers(self, tag=MATCH_ALL_TAG, *args, **kwargs):
         """
         Returns all of our servers dynamically build based on parsed
         configuration.
@@ -165,15 +196,16 @@ def servers(self, tag=MATCH_ALL_TAG, cache=True):
                     logic=tag, data=entry.tags, match_all=MATCH_ALL_TAG):
                 # Build ourselves a list of services dynamically and return the
                 # as a list
-                response.extend(entry.servers(cache=cache))
+                response.extend(entry.servers())
 
         return response
 
     @staticmethod
-    def instantiate(url, asset=None, tag=None, suppress_exceptions=True):
+    def instantiate(url, asset=None, tag=None, cache=None,
+                    suppress_exceptions=True):
         """
         Returns the instance of a instantiated configuration plugin based on
-        the provided Server URL.  If the url fails to be parsed, then None
+        the provided Config URL.  If the url fails to be parsed, then None
         is returned.
 
         """
@@ -210,6 +242,10 @@ def instantiate(url, asset=None, tag=None, suppress_exceptions=True):
         results['asset'] = \
             asset if isinstance(asset, AppriseAsset) else AppriseAsset()
 
+        if cache is not None:
+            # Force an over-ride of the cache value to what we have specified
+            results['cache'] = cache
+
         if suppress_exceptions:
             try:
                 # Attempt to create an instance of our plugin using the parsed
@@ -261,10 +297,11 @@ def server_pop(self, index):
         # If we reach here, then we indexed out of range
         raise IndexError('list index out of range')
 
-    def pop(self, index):
+    def pop(self, index=-1):
         """
-        Removes an indexed Apprise Configuration from the stack and
-        returns it.
+        Removes an indexed Apprise Configuration from the stack and returns it.
+
+        By default, the last element is removed from the list
         """
         # Remove our entry
         return self.configs.pop(index)

apprise/attachment/AttachBase.py

@@ -109,12 +109,14 @@ def __init__(self, name=None, mimetype=None, cache=True, **kwargs):
         # Absolute path to attachment
         self.download_path = None
 
-        # Set our cache flag
-        # it can be True, or an integer
+        # Set our cache flag; it can be True or a (positive) integer
         try:
             self.cache = cache if isinstance(cache, bool) else int(cache)
             if self.cache < 0:
-                raise ValueError()
+                err = 'A negative cache value ({}) was specified.'.format(
+                    cache)
+                self.logger.warning(err)
+                raise TypeError(err)
 
         except (ValueError, TypeError):
             err = 'An invalid cache value ({}) was specified.'.format(cache)
@@ -212,7 +214,8 @@ def exists(self):
         if self.download_path and os.path.isfile(self.download_path) \
                 and self.cache:
 
-            # We have enough reason to look further into our cached value
+            # We have enough reason to look further into our cached content
+            # and verify it has not expired.
             if self.cache is True:
                 # return our fixed content as is; we will always cache it
                 return True