# -*- coding: utf-8 -*- # # Copyright (C) 2019 Chris Caron # All rights reserved. # # This code is licensed under the MIT License. # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files(the "Software"), to deal # in the Software without restriction, including without limitation the rights # to use, copy, modify, merge, publish, distribute, sublicense, and / or sell # copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions : # # The above copyright notice and this permission notice shall be included in # all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN # THE SOFTWARE. import os import re import six import yaml import time from .. import plugins from ..AppriseAsset import AppriseAsset from ..URLBase import URLBase from ..common import ConfigFormat from ..common import CONFIG_FORMATS from ..utils import GET_SCHEMA_RE from ..utils import parse_list from ..utils import parse_bool class ConfigBase(URLBase): """ This is the base class for all supported configuration sources """ # The Default Encoding to use if not otherwise detected encoding = 'utf-8' # The default expected configuration format unless otherwise # detected by the sub-modules default_config_format = ConfigFormat.TEXT # This is only set if the user overrides the config format on the URL # this should always initialize itself as None config_format = None # Don't read any more of this amount of data into memory as there is no # reason we should be reading in more. This is more of a safe guard then # anything else. 128KB (131072B) max_buffer_size = 131072 def __init__(self, cache=True, **kwargs): """ Initialize some general logging and common server arguments that will keep things consistent when working with the configurations that inherit this class. By default we cache our responses so that subsiquent calls does not cause the content to be retrieved again. For local file references this makes no difference at all. But for remote content, this does mean more then one call can be made to retrieve the (same) data. This method can be somewhat inefficient if disabled. 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. """ super(ConfigBase, self).__init__(**kwargs) # Tracks the time the content was last retrieved on. This place a role # for cases where we are not caching our response and are required to # re-retrieve our settings. self._cached_time = None # Tracks previously loaded content for speed self._cached_servers = None if 'encoding' in kwargs: # Store the encoding self.encoding = kwargs.get('encoding') if 'format' in kwargs \ and isinstance(kwargs['format'], six.string_types): # Store the enforced config format self.config_format = kwargs.get('format').lower() if self.config_format not in CONFIG_FORMATS: # Simple error checking err = 'An invalid config format ({}) was specified.'.format( self.config_format) self.logger.warning(err) raise TypeError(err) # 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: 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) self.logger.warning(err) raise TypeError(err) return def servers(self, asset=None, **kwargs): """ Performs reads loaded configuration and returns all of the services that could be parsed and loaded. """ if not self.expired(): # We already have cached results to return; use them return self._cached_servers # Our cached response object self._cached_servers = list() # read() causes the child class to do whatever it takes for the # config plugin to load the data source and return unparsed content # None is returned if there was an error or simply no data content = self.read(**kwargs) if not isinstance(content, six.string_types): # Set the time our content was cached at self._cached_time = time.time() # Nothing more to do; return our empty cache list return self._cached_servers # Our Configuration format uses a default if one wasn't one detected # or enfored. config_format = \ self.default_config_format \ if self.config_format is None else self.config_format # Dynamically load our parse_ function based on our config format fn = getattr(ConfigBase, 'config_parse_{}'.format(config_format)) # Execute our config parse function which always returns a list self._cached_servers.extend(fn(content=content, asset=asset)) if len(self._cached_servers): self.logger.info('Loaded {} entries from {}'.format( len(self._cached_servers), self.url())) else: self.logger.warning('Failed to load configuration from {}'.format( self.url())) # Set the time our content was cached at self._cached_time = time.time() return self._cached_servers def read(self): """ This object should be implimented by the child classes """ return None def expired(self): """ Simply returns True if the configuration should be considered as expired or False if content should be retrieved. """ if isinstance(self._cached_servers, list) and self.cache: # We have enough reason to look further into our cached content # and verify it has not expired. if self.cache is True: # we have not expired, return False return False # Verify our cache time to determine whether we will get our # content again. age_in_sec = time.time() - self._cached_time if age_in_sec <= self.cache: # We have not expired; return False return False # If we reach here our configuration should be considered # missing and/or expired. return True @staticmethod def parse_url(url, verify_host=True): """Parses the URL and returns it broken apart into a dictionary. This is very specific and customized for Apprise. Args: url (str): The URL you want to fully parse. verify_host (:obj:`bool`, optional): a flag kept with the parsed URL which some child classes will later use to verify SSL keys (if SSL transactions take place). Unless under very specific circumstances, it is strongly recomended that you leave this default value set to True. Returns: A dictionary is returned containing the URL fully parsed if successful, otherwise None is returned. """ results = URLBase.parse_url(url, verify_host=verify_host) if not results: # We're done; we failed to parse our url return results # Allow overriding the default config format if 'format' in results['qsd']: results['format'] = results['qsd'].get('format') if results['format'] not in CONFIG_FORMATS: URLBase.logger.warning( 'Unsupported format specified {}'.format( results['format'])) del results['format'] # Defines the encoding of the payload if 'encoding' in results['qsd']: results['encoding'] = results['qsd'].get('encoding') # Our cache value if 'cache' in results['qsd']: # First try to get it's integer value try: results['cache'] = int(results['qsd']['cache']) except (ValueError, TypeError): # No problem, it just isn't an integer; now treat it as a bool # instead: results['cache'] = parse_bool(results['qsd']['cache']) return results @staticmethod def detect_config_format(content, **kwargs): """ Takes the specified content and attempts to detect the format type The function returns the actual format type if detected, otherwise it returns None """ # Detect Format Logic: # - A pound/hashtag (#) is alawys a comment character so we skip over # lines matched here. # - Detection begins on the first non-comment and non blank line # matched. # - If we find a string followed by a colon, we know we're dealing # with a YAML file. # - If we find a string that starts with a URL, or our tag # definitions (accepting commas) followed by an equal sign we know # we're dealing with a TEXT format. # Define what a valid line should look like valid_line_re = re.compile( r'^\s*(?P([;#]+(?P.*))|' r'(?P((?P[ \t,a-z0-9_-]+)=)?[a-z0-9]+://.*)|' r'((?P[a-z0-9]+):.*))?$', re.I) try: # split our content up to read line by line content = re.split(r'\r*\n', content) except TypeError: # content was not expected string type ConfigBase.logger.error('Invalid apprise config specified') return None # By default set our return value to None since we don't know # what the format is yet config_format = None # iterate over each line of the file to attempt to detect it # stop the moment a the type has been determined for line, entry in enumerate(content, start=1): result = valid_line_re.match(entry) if not result: # Invalid syntax ConfigBase.logger.error( 'Undetectable apprise configuration found ' 'based on line {}.'.format(line)) # Take an early exit return None # Attempt to detect configuration if result.group('yaml'): config_format = ConfigFormat.YAML ConfigBase.logger.debug( 'Detected YAML configuration ' 'based on line {}.'.format(line)) break elif result.group('text'): config_format = ConfigFormat.TEXT ConfigBase.logger.debug( 'Detected TEXT configuration ' 'based on line {}.'.format(line)) break # If we reach here, we have a comment entry # Adjust default format to TEXT config_format = ConfigFormat.TEXT return config_format @staticmethod def config_parse(content, asset=None, config_format=None, **kwargs): """ Takes the specified config content and loads it based on the specified config_format. If a format isn't specified, then it is auto detected. """ if config_format is None: # Detect the format config_format = ConfigBase.detect_config_format(content) if not config_format: # We couldn't detect configuration ConfigBase.logger.error('Could not detect configuration') return list() if config_format not in CONFIG_FORMATS: # Invalid configuration type specified ConfigBase.logger.error( 'An invalid configuration format ({}) was specified'.format( config_format)) return list() # Dynamically load our parse_ function based on our config format fn = getattr(ConfigBase, 'config_parse_{}'.format(config_format)) # Execute our config parse function which always returns a list return fn(content=content, asset=asset) @staticmethod def config_parse_text(content, asset=None): """ Parse the specified content as though it were a simple text file only containing a list of URLs. Return a list of loaded notification plugins Optionally associate an asset with the notification. The file syntax is: # # pound/hashtag allow for line comments # # One or more tags can be idenified using comma's (,) to separate # them. = # Or you can use this format (no tags associated) """ response = list() # Define what a valid line should look like valid_line_re = re.compile( r'^\s*(?P([;#]+(?P.*))|' r'(\s*(?P[^=]+)=|=)?\s*' r'(?P[a-z0-9]{2,9}://.*))?$', re.I) try: # split our content up to read line by line content = re.split(r'\r*\n', content) except TypeError: # content was not expected string type ConfigBase.logger.error('Invalid apprise text data specified') return list() for line, entry in enumerate(content, start=1): result = valid_line_re.match(entry) if not result: # Invalid syntax ConfigBase.logger.error( 'Invalid apprise text format found ' '{} on line {}.'.format(entry, line)) # Assume this is a file we shouldn't be parsing. It's owner # can read the error printed to screen and take action # otherwise. return list() # Store our url read in url = result.group('url') if not url: # Comment/empty line; do nothing continue # Acquire our url tokens results = plugins.url_to_dict(url) if results is None: # Failed to parse the server URL ConfigBase.logger.warning( 'Unparseable URL {} on line {}.'.format(url, line)) continue # Build a list of tags to associate with the newly added # notifications if any were set results['tag'] = set(parse_list(result.group('tags'))) ConfigBase.logger.trace( 'URL {} unpacked as:{}{}'.format( url, os.linesep, os.linesep.join( ['{}="{}"'.format(k, v) for k, v in results.items()]))) # Prepare our Asset Object results['asset'] = \ asset if isinstance(asset, AppriseAsset) else AppriseAsset() try: # Attempt to create an instance of our plugin using the # parsed URL information plugin = plugins.SCHEMA_MAP[results['schema']](**results) # Create log entry of loaded URL ConfigBase.logger.debug('Loaded URL: {}'.format(plugin.url())) except Exception as e: # the arguments are invalid or can not be used. ConfigBase.logger.warning( 'Could not load URL {} on line {}.'.format( url, line)) ConfigBase.logger.debug('Loading Exception: %s' % str(e)) continue # if we reach here, we successfully loaded our data response.append(plugin) # Return what was loaded return response @staticmethod def config_parse_yaml(content, asset=None): """ Parse the specified content as though it were a yaml file specifically formatted for apprise. Return a list of loaded notification plugins. Optionally associate an asset with the notification. """ response = list() try: # Load our data (safely) result = yaml.load(content, Loader=yaml.SafeLoader) except (AttributeError, yaml.error.MarkedYAMLError) as e: # Invalid content ConfigBase.logger.error( 'Invalid apprise yaml data specified.') ConfigBase.logger.debug( 'YAML Exception:{}{}'.format(os.linesep, e)) return list() if not isinstance(result, dict): # Invalid content ConfigBase.logger.error('Invalid apprise yaml structure specified') return list() # YAML Version version = result.get('version', 1) if version != 1: # Invalid syntax ConfigBase.logger.error( 'Invalid apprise yaml version specified {}.'.format(version)) return list() # # global asset object # asset = asset if isinstance(asset, AppriseAsset) else AppriseAsset() tokens = result.get('asset', None) if tokens and isinstance(tokens, dict): for k, v in tokens.items(): if k.startswith('_') or k.endswith('_'): # Entries are considered reserved if they start or end # with an underscore ConfigBase.logger.warning( 'Ignored asset key "{}".'.format(k)) continue if not (hasattr(asset, k) and isinstance(getattr(asset, k), six.string_types)): # We can't set a function or non-string set value ConfigBase.logger.warning( 'Invalid asset key "{}".'.format(k)) continue if v is None: # Convert to an empty string v = '' if not isinstance(v, six.string_types): # we must set strings with a string ConfigBase.logger.warning( 'Invalid asset value to "{}".'.format(k)) continue # Set our asset object with the new value setattr(asset, k, v.strip()) # # global tag root directive # global_tags = set() tags = result.get('tag', None) if tags and isinstance(tags, (list, tuple, six.string_types)): # Store any preset tags global_tags = set(parse_list(tags)) # # urls root directive # urls = result.get('urls', None) if not isinstance(urls, (list, tuple)): # Unsupported ConfigBase.logger.error( 'Missing "urls" directive in apprise yaml.') return list() # Iterate over each URL for no, url in enumerate(urls): # Our results object is what we use to instantiate our object if # we can. Reset it to None on each iteration results = list() if isinstance(url, six.string_types): # We're just a simple URL string... schema = GET_SCHEMA_RE.match(url) if schema is None: # Log invalid entries so that maintainer of config # config file at least has something to take action # with. ConfigBase.logger.warning( 'Invalid URL {}, entry #{}'.format(url, no + 1)) continue # We found a valid schema worthy of tracking; store it's # details: _results = plugins.url_to_dict(url) if _results is None: ConfigBase.logger.warning( 'Unparseable URL {}, entry #{}'.format( url, no + 1)) continue # add our results to our global set results.append(_results) elif isinstance(url, dict): # We are a url string with additional unescaped options. In # this case we want to iterate over all of our options so we # can at least tell the end user what entries were ignored # due to errors if six.PY2: it = url.iteritems() else: # six.PY3 it = iter(url.items()) # Track the URL to-load _url = None # Track last acquired schema schema = None for key, tokens in it: # Test our schema _schema = GET_SCHEMA_RE.match(key) if _schema is None: # Log invalid entries so that maintainer of config # config file at least has something to take action # with. ConfigBase.logger.warning( 'Ignored entry {} found under urls, entry #{}' .format(key, no + 1)) continue # Store our URL and Schema Regex _url = key # Store our schema schema = _schema.group('schema').lower() if _url is None: # the loop above failed to match anything ConfigBase.logger.warning( 'Unsupported schema in urls, entry #{}'.format(no + 1)) continue _results = plugins.url_to_dict(_url) if _results is None: # Setup dictionary _results = { # Minimum requirements 'schema': schema, } if isinstance(tokens, (list, tuple, set)): # populate and/or override any results populated by # parse_url() for entries in tokens: # Copy ourselves a template of our parsed URL as a base # to work with r = _results.copy() # We are a url string with additional unescaped options if isinstance(entries, dict): if six.PY2: _url, tokens = next(url.iteritems()) else: # six.PY3 _url, tokens = next(iter(url.items())) # Tags you just can't over-ride if 'schema' in entries: del entries['schema'] # Extend our dictionary with our new entries r.update(entries) # add our results to our global set results.append(r) else: # add our results to our global set results.append(_results) else: # Unsupported ConfigBase.logger.warning( 'Unsupported apprise yaml entry #{}'.format(no + 1)) continue # Track our entries entry = 0 while len(results): # Increment our entry count entry += 1 # Grab our first item _results = results.pop(0) # tag is a special keyword that is managed by apprise object. # The below ensures our tags are set correctly if 'tag' in _results: # Tidy our list up _results['tag'] = \ set(parse_list(_results['tag'])) | global_tags else: # Just use the global settings _results['tag'] = global_tags ConfigBase.logger.trace( 'URL #{}: {} unpacked as:{}{}' .format(no + 1, url, os.linesep, os.linesep.join( ['{}="{}"'.format(k, a) for k, a in _results.items()]))) # Prepare our Asset Object _results['asset'] = asset try: # Attempt to create an instance of our plugin using the # parsed URL information plugin = plugins.SCHEMA_MAP[_results['schema']](**_results) # Create log entry of loaded URL ConfigBase.logger.debug( 'Loaded URL: {}'.format(plugin.url())) except Exception: # the arguments are invalid or can not be used. ConfigBase.logger.warning( 'Could not load apprise yaml entry #{}, item #{}' .format(no + 1, entry)) continue # if we reach here, we successfully loaded our data response.append(plugin) return response def pop(self, index=-1): """ Removes an indexed Notification Service from the stack and returns it. By default, the last element of the list is removed. """ if not isinstance(self._cached_servers, list): # Generate ourselves a list of content we can pull from self.servers() # Pop the element off of the stack return self._cached_servers.pop(index) def __getitem__(self, index): """ Returns the indexed server entry associated with the loaded notification servers """ if not isinstance(self._cached_servers, list): # Generate ourselves a list of content we can pull from self.servers() return self._cached_servers[index] def __iter__(self): """ Returns an iterator to our server list """ if not isinstance(self._cached_servers, list): # Generate ourselves a list of content we can pull from self.servers() return iter(self._cached_servers) def __len__(self): """ Returns the total number of servers loaded """ if not isinstance(self._cached_servers, list): # Generate ourselves a list of content we can pull from self.servers() return len(self._cached_servers) def __bool__(self): """ Allows the Apprise object to be wrapped in an Python 3.x based 'if statement'. True is returned if our content was downloaded correctly. """ if not isinstance(self._cached_servers, list): # Generate ourselves a list of content we can pull from self.servers() return True if self._cached_servers else False def __nonzero__(self): """ Allows the Apprise object to be wrapped in an Python 2.x based 'if statement'. True is returned if our content was downloaded correctly. """ if not isinstance(self._cached_servers, list): # Generate ourselves a list of content we can pull from self.servers() return True if self._cached_servers else False